chrome.debugger

תיאור

‫chrome.debugger API משמש כהעברה חלופית לפרוטוקול לניפוי באגים מרחוק של Chrome. אפשר להשתמש ב-chrome.debugger כדי לצרף כרטיסייה אחת או יותר למכשיר, כדי לבצע אינטראקציה עם הרשת, לנפות באגים ב-JavaScript, לשנות את ה-DOM ואת ה-CSS ועוד. משתמשים במאפיין Debuggee tabId כדי לטרגט כרטיסיות עם sendCommand ולנתב אירועים לפי tabId מתוך קריאות חוזרות (callback) של onEvent.

הרשאות

debugger

כדי להשתמש ב-API הזה, צריך להצהיר על ההרשאה "debugger" במניפסט של התוסף.

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

מושגים ושימוש

אחרי שמצרפים את chrome.debugger API, אפשר לשלוח פקודות של פרוטוקול כלי הפיתוח ל-Chrome‏ (CDP) ליעד נתון. הסבר מפורט על CDP חורג מהיקף התיעוד הזה. כדי לקבל מידע נוסף על CDP, אפשר לעיין בתיעוד הרשמי של CDP.

יעדים

יעדים מייצגים משהו שמבצעים בו ניפוי באגים – זה יכול לכלול כרטיסייה, iframe או worker. כל יעד מזוהה על ידי מזהה ייחודי אוניברסלי (UUID) ויש לו סוג משויך (כמו iframe,‏ shared_worker ועוד).

בתוך יעד יכולים להיות כמה הקשרים של ביצוע – לדוגמה, אם יש iframe באותו תהליך, הוא לא מקבל יעד ייחודי אלא מיוצג כהקשרים שונים שאפשר לגשת אליהם מיעד יחיד.

דומיינים מוגבלים

מסיבות אבטחה, ה-API‏ chrome.debugger לא מספק גישה לכל הדומיינים של פרוטוקול כלי הפיתוח ל-Chrome. הדומיינים הזמינים הם: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio

עבודה עם מסגרות

אין מיפוי של אחד לאחד בין פריימים ליעדים. בכרטיסייה אחת, יכול להיות שלמספר פריימים של אותו תהליך יהיה אותו יעד, אבל הם ישתמשו בהקשר ביצוע שונה. לעומת זאת, יכול להיות שייווצר יעד חדש ל-iframe שפועל מחוץ לתהליך.

כדי לצרף לכל המסגרות, צריך לטפל בכל סוג של מסגרת בנפרד:

  • כדי לזהות הקשרים חדשים של ביצוע שמשויכים לאותם פריימים של תהליך, צריך להאזין לאירוע Runtime.executionContextCreated.

  • כדי לזהות פריימים מחוץ לתהליך, פועלים לפי השלבים לצירוף ליעדים קשורים.

אחרי שמתחברים ליעד, יכול להיות שתרצו להתחבר ליעדים קשורים נוספים, כולל מסגרות צאצא מחוץ לתהליך או עובדים משויכים.

החל מ-Chrome 125, ‏ chrome.debugger API תומך בפעילויות שטוחות. כך תוכלו להוסיף יעדים נוספים כצאצאים לסשן הניפוי הראשי ולשלוח להם הודעות בלי צורך לבצע עוד קריאה ל-chrome.debugger.attach. במקום זאת, אפשר להוסיף מאפיין sessionId כשמתקשרים אל chrome.debugger.sendCommand כדי לזהות את יעד הצאצא שאליו רוצים לשלוח פקודה.

כדי לצרף אוטומטית למסגרות צאצא מחוץ לתהליך, קודם צריך להוסיף מאזין לאירוע Target.attachedToTarget:

chrome.debugger.onEvent.addListener((source, method, params) => {
  if (method === "Target.attachedToTarget") {
    // `source` identifies the parent session, but we need to construct a new
    // identifier for the child session
    const session = { ...source, sessionId: params.sessionId };

    // Call any needed CDP commands for the child session
    await chrome.debugger.sendCommand(session, "Runtime.enable");
  }
});

לאחר מכן, מפעילים את הצירוף האוטומטי על ידי שליחת הפקודה Target.setAutoAttach עם האפשרות flatten שמוגדרת לערך true:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

ההצמדה האוטומטית מתבצעת רק למסגרות שהיעד מודע להן, והיא מוגבלת למסגרות שהן צאצאים ישירים של מסגרת שמשויכת אליו. לדוגמה, בהיררכיית המסגרות A -> B -> C (שבה כל המסגרות הן חוצות-מקורות), קריאה ל-Target.setAutoAttach עבור היעד שמשויך ל-A תגרום לכך שהסשן ישויך גם ל-B. עם זאת, הפעולה הזו לא חוזרת על עצמה, ולכן צריך לקרוא גם ל-Target.setAutoAttach כדי ש-B יצרף את הסשן ל-C.

דוגמאות

כדי לנסות את ה-API הזה, מתקינים את דוגמת ה-API של כלי הניפוי באגים ממאגר chrome-extension-samples.

סוגים

Debuggee

מזהה של תהליך לניפוי באגים. צריך לציין את tabId, ‏ extensionId או targetId

מאפיינים

  • extensionId

    מחרוזת אופציונלי

    המזהה של התוסף שרוצים לבצע בו ניפוי באגים. אפשר לצרף לדף הרקע של תוסף רק כשמשתמשים במתג --silent-debugger-extension-api של שורת הפקודה.

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים לנפות בה באגים.

  • targetId

    מחרוזת אופציונלי

    המזהה האטום של יעד ניפוי הבאגים.

DebuggerSession

‫Chrome 125 ואילך

מזהה סשן של כלי לניפוי באגים. צריך לציין את אחד מהערכים tabId, ‏ extensionId או targetId. בנוסף, אפשר לספק sessionId אופציונלי. אם sessionId מצוין בארגומנטים שנשלחים מ-onEvent, המשמעות היא שהאירוע מגיע מסשן של פרוטוקול צאצא בסשן של פרוטוקול המאגר. אם מציינים sessionId כשמעבירים אותו אל sendCommand, הוא מכוון לסשן של פרוטוקול צאצא בתוך סשן הניפוי באגים של השורש.

מאפיינים

  • extensionId

    מחרוזת אופציונלי

    המזהה של התוסף שרוצים לבצע בו ניפוי באגים. אפשר לצרף לדף הרקע של תוסף רק כשמשתמשים במתג --silent-debugger-extension-api של שורת הפקודה.

  • sessionId

    מחרוזת אופציונלי

    המזהה האטום של הסשן של פרוטוקול כלי הפיתוח ל-Chrome. מזהה סשן צאצא בסשן הבסיס שמזוהה על ידי tabId, ‏ extensionId או targetId.

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים לנפות בה באגים.

  • targetId

    מחרוזת אופציונלי

    המזהה האטום של יעד ניפוי הבאגים.

DetachReason

‫Chrome 44 ואילך

הסיבה לסיום החיבור.

Enum

‫"target_closed"

‫"canceled_by_user"

TargetInfo

מידע על יעד ניפוי הבאגים

מאפיינים

  • מצורף

    בוליאני

    הערך הוא True אם ניפוי הבאגים כבר מצורף.

  • extensionId

    מחרוזת אופציונלי

    מזהה התוסף, מוגדר אם type = 'background_page'.

  • faviconUrl

    מחרוזת אופציונלי

    כתובת ה-URL של סמל האתר של היעד.

  • id [מזהה]

    מחרוזת

    מזהה היעד.

  • tabId

    מספר אופציונלי

    מזהה הכרטיסייה, מוגדר אם type == 'page'.

  • title

    מחרוזת

    כותרת דף היעד.

  • סוג היעד.

  • כתובת אתר

    מחרוזת

    כתובת היעד.

TargetInfoType

‫Chrome 44 ואילך

סוג היעד.

Enum

‫"page"

"background_page"

‫‎"worker"‎

"other"

Methods

attach()

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

מצרף את מאתר הבאגים ליעד שצוין.

פרמטרים

  • יעד

    Debuggee

    יעד לניפוי באגים שאליו רוצים לצרף.

  • requiredVersion

    מחרוזת

    גרסת פרוטוקול הניפוי הנדרשת ("0.1"). אפשר לצרף רק ל-debuggee עם גרסה ראשית תואמת וגרסה משנית גדולה או שווה. כאן אפשר לראות את רשימת הגרסאות של הפרוטוקול.

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

detach()

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

מנתק את מאתר הבאגים מהיעד הנתון.

פרמטרים

  • יעד

    Debuggee

    יעד לניפוי באגים שממנו רוצים להתנתק.

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

מחזירה את רשימת יעדי הניפוי באגים הזמינים.

החזרות

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

שליחת הפקודה שצוינה ליעד הניפוי.

פרמטרים

  • יעד ניפוי הבאגים שאליו רוצים לשלוח את הפקודה.

  • method

    מחרוזת

    שם ה-method. צריך לבחור אחת מהשיטות שמוגדרות בפרוטוקול לניפוי באגים מרחוק.

  • commandParams

    אובייקט אופציונלי

    אובייקט JSON עם פרמטרים של בקשה. האובייקט הזה צריך להתאים לסכימת הפרמטרים של ניפוי באגים מרחוק עבור השיטה הנתונה.

החזרות

  • Promise<object | undefined>

    ‫Chrome 96 ואילך

אירועים

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

האירוע מופעל כשהדפדפן מסיים את סשן הניפוי באגים של הכרטיסייה. המצב הזה קורה כשסוגרים את הכרטיסייה או כשמפעילים את כלי הפיתוח של Chrome עבור הכרטיסייה המצורפת.

פרמטרים

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

מופעל בכל פעם שמתרחש אירוע של מכשור לבעיות בניפוי באגים של יעד.

פרמטרים

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (source: DebuggerSession, method: string, params?: object) => void

    • method

      מחרוזת

    • params

      אובייקט אופציונלי