browser.debugger

תיאור

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

הרשאות

debugger

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

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

הגבלות מדיניות של Enterprise

במכשירים ארגוניים, כללי מדיניות מסוימים יכולים להגביל תוספים מלצרף את מנקה הבאגים באמצעות מודל של "הכול או כלום" בזמן הצירוף (browser.debugger.attach()):

  • מארחים מוגבלים: אם מדיניות הארגון ExtensionSettings מגדירה מארחים חסומים (runtime_blocked_hosts) לתוסף, browser.debugger.attach() נחסם בכל היעדים עם השגיאה "Host access is restricted by policy." (גם אם מקורות ספציפיים נמצאים ב-runtime_allowed_hosts).
  • כללי מדיניות של צילומי מסך ו-DLP: אם מדיניות הארגון DisableScreenshots משביתה את צילום המסך או שכללי מניעת אובדן נתונים (DLP) חלים על היעד, הפעולה browser.debugger.attach() נכשלת עם השגיאה "Screenshot capture is restricted by policy.".

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

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

יעדים

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

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

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

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

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

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

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

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

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

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

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

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

browser.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 browser.debugger.sendCommand(session, "Runtime.enable");
  }
});

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

await browser.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 הזה, מתקינים את הדוגמה של debugger API ממאגר chrome-extension-samples.

סוגים

Debuggee

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

מאפיינים

  • extensionId

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

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

  • tabId

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

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

  • targetId

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

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

DebuggerSession

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

מאפיינים

  • extensionId

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

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

  • sessionId

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

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

  • tabId

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

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

  • targetId

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

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

DetachReason

Chrome 44 ואילך browser.* ‎ מ-Chrome 148

הסיבה לסגירת החיבור.

טיפוסים בני מנייה (enum)

"target_closed"

"canceled_by_user"

TargetInfo

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

מאפיינים

  • מצורף

    בוליאני

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

  • extensionId

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

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

  • faviconUrl

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

    כתובת ה-URL של סמל האתר המטורגט.

  • id [מזהה]

    מחרוזת

    מזהה היעד.

  • tabId

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

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

  • title

    מחרוזת

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

  • סוג היעד.

  • url

    מחרוזת

    כתובת ה-URL של היעד.

TargetInfoType

Chrome 44 ואילך browser.* ‎ מ-Chrome 148

סוג היעד.

טיפוסים בני מנייה (enum)

"page"

"background_page"

"worker"

"other"

Methods

attach()

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

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

פרמטרים

  • יעד

    Debuggee

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

  • requiredVersion

    מחרוזת

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    הפעולה מסתיימת כשהצירוף מצליח או נכשל. ה-promise מסתיים ללא ערך. אם הצירוף נכשל, ה-promise יידחה.

detach()

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

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

פרמטרים

  • יעד

    Debuggee

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

getTargets()

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

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

החזרות

  • Promise<TargetInfo[]>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

sendCommand()

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

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

פרמטרים

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

  • method

    מחרוזת

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

  • commandParams

    object optional

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

החזרות

  • Promise<object | undefined>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

    גוף התגובה. אם תתרחש שגיאה במהלך פרסום ההודעה, ההבטחה תידחה.

אירועים

onDetach

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

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

פרמטרים

onEvent

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

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

פרמטרים

  • callback

    פונקציה

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

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

    • method

      מחרוזת

    • פרמטרים

      object optional