browser.permissions

คำอธิบาย

ใช้ chrome.permissions API เพื่อขอสิทธิ์ที่ไม่บังคับซึ่งประกาศไว้ในรันไทม์แทนเวลาติดตั้ง เพื่อให้ผู้ใช้เข้าใจว่าเหตุใดจึงต้องใช้สิทธิ์และให้สิทธิ์เฉพาะที่จำเป็นเท่านั้น

แนวคิดและการใช้งาน

คำเตือนเกี่ยวกับสิทธิ์มีไว้เพื่ออธิบายความสามารถที่ API มอบให้ แต่คำเตือนบางอย่างอาจไม่ชัดเจน Permissions API ช่วยให้นักพัฒนาแอปอธิบายคำเตือนเกี่ยวกับสิทธิ์และแนะนำฟีเจอร์ใหม่ๆ ได้อย่างค่อยเป็นค่อยไป ซึ่งจะช่วยให้ผู้ใช้ได้รู้จักส่วนขยายโดยไม่มีความเสี่ยง วิธีนี้ช่วยให้ผู้ใช้ระบุระดับการเข้าถึงที่ยินดีให้และฟีเจอร์ที่ต้องการเปิดใช้ได้

ตัวอย่างเช่น ฟังก์ชันหลักของส่วนขยายสิทธิ์ที่ไม่บังคับคือการลบล้างหน้าแท็บใหม่ ฟีเจอร์หนึ่งคือการแสดงเป้าหมายของผู้ใช้ในวันนั้น ฟีเจอร์นี้ต้องใช้สิทธิ์พื้นที่เก็บข้อมูลเท่านั้น ซึ่งไม่มีคำเตือน ส่วนขยายมีฟีเจอร์เพิ่มเติมที่ผู้ใช้เปิดใช้ได้โดยคลิกปุ่มต่อไปนี้

ปุ่มส่วนขยายที่เปิดใช้ฟีเจอร์เพิ่มเติม
ปุ่มส่วนขยายที่เปิดใช้ฟีเจอร์เพิ่มเติม

การแสดงเว็บไซต์ยอดนิยมของผู้ใช้ต้องใช้สิทธิ์ topSites ซึ่งมีคำเตือนต่อไปนี้

คำเตือนเกี่ยวกับส่วนขยายสำหรับ topSites API
คำเตือนเกี่ยวกับส่วนขยายสำหรับ topSites API

ใช้สิทธิ์ที่ไม่บังคับ

ขั้นตอนที่ 1: ตัดสินใจว่าสิทธิ์ใดจำเป็นและสิทธิ์ใดไม่บังคับ

ส่วนขยายสามารถประกาศสิทธิ์ทั้งแบบจำเป็นและไม่บังคับได้ โดยทั่วไป คุณควรทำดังนี้

  • ใช้สิทธิ์ที่จำเป็นเมื่อจำเป็นสำหรับฟังก์ชันพื้นฐานของส่วนขยาย
  • ใช้สิทธิ์ที่ไม่บังคับเมื่อจำเป็นสำหรับฟีเจอร์ที่ไม่บังคับในส่วนขยาย

ข้อดีของสิทธิ์ที่จำเป็น

  • ข้อความแจ้งน้อยลง: ส่วนขยายสามารถแจ้งให้ผู้ใช้ยอมรับสิทธิ์ทั้งหมดได้ในครั้งเดียว
  • การพัฒนาที่ง่ายขึ้น: รับประกันว่าสิทธิ์ที่จำเป็นจะปรากฏอยู่

ข้อดีของสิทธิ์ที่ไม่บังคับมีดังนี้

  • ความปลอดภัยที่ดีขึ้น: ส่วนขยายจะทำงานโดยใช้สิทธิ์น้อยลงเนื่องจากผู้ใช้จะเปิดใช้เฉพาะสิทธิ์ที่จำเป็นเท่านั้น
  • ข้อมูลที่ดีขึ้นสำหรับผู้ใช้: ส่วนขยายสามารถอธิบายเหตุผลที่ต้องใช้สิทธิ์บางอย่างเมื่อผู้ใช้เปิดใช้ฟีเจอร์ที่เกี่ยวข้อง
  • อัปเกรดได้ง่ายขึ้น: เมื่อคุณอัปเกรดส่วนขยาย Chrome จะไม่ปิดใช้ส่วนขยายสำหรับผู้ใช้หากการอัปเกรดเพิ่มสิทธิ์ที่ไม่บังคับแทนสิทธิ์ที่จำเป็น

ขั้นตอนที่ 2: ประกาศสิทธิ์ที่ไม่บังคับในไฟล์ Manifest

ประกาศสิทธิ์ที่ไม่บังคับในไฟล์ Manifest ของส่วนขยายด้วยคีย์ optional_permissions โดยใช้รูปแบบเดียวกับช่อง permissions ดังนี้

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

หากต้องการขอโฮสต์ที่คุณค้นพบเฉพาะในรันไทม์ ให้ใส่ "https://*/*" ในช่อง optional_host_permissions ของส่วนขยาย ซึ่งจะช่วยให้คุณระบุต้นทางใน "Permissions.origins" ได้ตราบใดที่มีรูปแบบที่ตรงกัน

สิทธิ์ที่ไม่สามารถระบุเป็นไม่บังคับได้

สิทธิ์ส่วนขยาย Chrome ส่วนใหญ่สามารถระบุเป็นแบบไม่บังคับได้ โดยมีข้อยกเว้นดังต่อไปนี้

สิทธิ์ คำอธิบาย
"debugger" browser.debugger API ทำหน้าที่เป็นตัวส่งทางเลือกสำหรับโปรโตคอลการแก้ไขข้อบกพร่องระยะไกลของ Chrome
"declarativeNetRequest" ให้สิทธิ์ส่วนขยายเข้าถึง API browser.declarativeNetRequest
"devtools" อนุญาตให้ส่วนขยายขยายฟังก์ชันการทำงานของ เครื่องมือสำหรับนักพัฒนาเว็บใน Chrome
"geolocation" อนุญาตให้ส่วนขยายใช้ API ตำแหน่งทางภูมิศาสตร์ของ HTML5
"mdns" ให้สิทธิ์เข้าถึง API browser.mdns แก่ส่วนขยาย
"proxy" ให้สิทธิ์เข้าถึง API browser.proxy แก่ส่วนขยายเพื่อจัดการการตั้งค่าพร็อกซีของ Chrome
"tts" API browser.tts จะเล่นการอ่านออกเสียงข้อความ (TTS) สังเคราะห์
"ttsEngine" browser.ttsEngine API ใช้เครื่องมืออ่านออกเสียงข้อความ (TTS) โดยใช้ส่วนขยาย
"wallpaper" ChromeOS เท่านั้น ใช้ API browser.wallpaper เพื่อเปลี่ยนวอลเปเปอร์ ChromeOS

ดูประกาศสิทธิ์เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับสิทธิ์ที่ใช้ได้และคำเตือนของสิทธิ์เหล่านั้น

ขั้นตอนที่ 3: ขอสิทธิ์ที่ไม่บังคับ

ขอสิทธิ์จากภายในท่าทางผู้ใช้โดยใช้ permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  browser.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

Chrome จะแจ้งให้ผู้ใช้ทราบหากการเพิ่มสิทธิ์ส่งผลให้เกิดข้อความเตือนที่แตกต่างจากที่ผู้ใช้เคยเห็นและยอมรับแล้ว ตัวอย่างเช่น โค้ดก่อนหน้าอาจส่งผลให้เกิดข้อความแจ้งดังนี้

ตัวอย่างข้อความแจ้งให้ยืนยันสิทธิ์
ตัวอย่างข้อความแจ้งให้ยืนยันสิทธิ์

ขั้นตอนที่ 4: ตรวจสอบสิทธิ์ปัจจุบันของส่วนขยาย

หากต้องการตรวจสอบว่าส่วนขยายมีสิทธิ์หรือชุดสิทธิ์ที่เฉพาะเจาะจงหรือไม่ ให้ใช้ permission.contains() ดังนี้

browser.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

ขั้นตอนที่ 5: นำสิทธิ์ออก

คุณควรนำสิทธิ์ออกเมื่อไม่ต้องการใช้แล้ว หลังจากนำสิทธิ์ออกแล้ว การเรียกใช้ permissions.request() มักจะเพิ่มสิทธิ์กลับมาโดยไม่แจ้งให้ผู้ใช้ทราบ

browser.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

ประเภท

Permissions

พร็อพเพอร์ตี้

  • origins

    string[] ไม่บังคับ

    รายการสิทธิ์ของโฮสต์ รวมถึงสิทธิ์ที่ระบุไว้ในคีย์ optional_permissions หรือ permissions ในไฟล์ Manifest และสิทธิ์ที่เชื่อมโยงกับสคริปต์เนื้อหา

  • สิทธิ์

    string[] ไม่บังคับ

    รายการสิทธิ์ที่มีชื่อ (ไม่รวมโฮสต์หรือต้นทาง)

เมธอด

addHostAccessRequest()

Chrome 133 ขึ้นไป browser.* ตั้งแต่ Chrome 148 MV3 ขึ้นไป 
browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

เพิ่มคำขอเข้าถึงโฮสต์ ระบบจะส่งสัญญาณคำขอไปยังผู้ใช้ก็ต่อเมื่อส่วนขยายได้รับสิทธิ์เข้าถึงโฮสต์ในคำขอเท่านั้น ระบบจะรีเซ็ตคำขอในการนำทางแบบข้ามต้นทาง เมื่อยอมรับแล้ว จะให้สิทธิ์เข้าถึงต้นทางระดับบนสุดของเว็บไซต์อย่างถาวร

พารามิเตอร์

  • ส่งคำขอ

    ออบเจ็กต์

    • documentId

      สตริง ไม่บังคับ

      รหัสของเอกสารที่แสดงคำขอเข้าถึงโฮสต์ได้ ต้องเป็นเอกสารระดับบนสุดภายในแท็บ หากระบุไว้ คำขอจะแสดงในแท็บของเอกสารที่ระบุ และจะถูกนำออกเมื่อเอกสารไปยังต้นทางใหม่ การเพิ่มคำขอใหม่จะลบล้างคำขอที่มีอยู่สำหรับ tabId ต้องระบุค่านี้หรือ tabId

    • รูปแบบ

      สตริง ไม่บังคับ

      รูปแบบ URL ที่แสดงคำขอเข้าถึงโฮสต์ได้ หากระบุไว้ คำขอเข้าถึงโฮสต์จะแสดงใน URL ที่ตรงกับรูปแบบนี้เท่านั้น

    • tabId

      number ไม่บังคับ

      รหัสของแท็บที่แสดงคำขอเข้าถึงโฮสต์ได้ หากระบุไว้ คำขอจะแสดงในแท็บที่ระบุและจะถูกนำออกเมื่อแท็บไปยังต้นทางใหม่ การเพิ่มคำขอใหม่จะลบล้างคำขอที่มีอยู่สำหรับ documentId ต้องระบุค่านี้หรือ documentId

การคืนสินค้า

  • Promise<void>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

ตรวจสอบว่าส่วนขยายมีสิทธิ์ที่ระบุหรือไม่

พารามิเตอร์

การคืนสินค้า

  • Promise<boolean>

    Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

getAll()

browser.permissions.getAll(): Promise<Permissions>

รับชุดสิทธิ์ปัจจุบันของส่วนขยาย

การคืนสินค้า

  • Promise<Permissions>

    Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

นำสิทธิ์เข้าถึงสิทธิ์ที่ระบุออก หากมีปัญหาในการนำสิทธิ์ออก ระบบจะปฏิเสธ Promise

พารามิเตอร์

การคืนสินค้า

  • Promise<boolean>

    Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

removeHostAccessRequest()

Chrome 133 ขึ้นไป browser.* ตั้งแต่ Chrome 148 MV3 ขึ้นไป 
browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

นำคำขอเข้าถึงโฮสต์ออก (หากมี)

พารามิเตอร์

  • ส่งคำขอ

    ออบเจ็กต์

    • documentId

      สตริง ไม่บังคับ

      รหัสของเอกสารที่จะนำคำขอเข้าถึงโฮสต์ออก ต้องเป็นเอกสารระดับบนสุดภายในแท็บ ต้องระบุค่านี้หรือ tabId

    • รูปแบบ

      สตริง ไม่บังคับ

      รูปแบบ URL ที่จะนำคำขอเข้าถึงโฮสต์ออก หากระบุไว้ ค่านี้ต้องตรงกับรูปแบบของคำขอเข้าถึงโฮสต์ที่มีอยู่ทุกประการ

    • tabId

      number ไม่บังคับ

      รหัสของแท็บที่จะนำคำขอเข้าถึงของโฮสต์ออก ต้องระบุค่านี้หรือ documentId

การคืนสินค้า

  • Promise<void>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

ขอสิทธิ์เข้าถึงสิทธิ์ที่ระบุ โดยแสดงข้อความแจ้งแก่ผู้ใช้หากจำเป็น สิทธิ์เหล่านี้ต้องกำหนดไว้ในช่อง optional_permissions ของไฟล์ Manifest หรือเป็นสิทธิ์ที่จำเป็นซึ่งผู้ใช้ระงับไว้ ระบบจะไม่สนใจเส้นทางในรูปแบบต้นทาง คุณสามารถขอชุดย่อยของสิทธิ์ต้นทางที่ไม่บังคับได้ เช่น หากระบุ *://*\/* ในส่วน optional_permissions ของไฟล์ Manifest คุณจะขอ http://example.com/ ได้ หากมีปัญหาในการขอสิทธิ์ ระบบจะปฏิเสธสัญญา

พารามิเตอร์

การคืนสินค้า

  • Promise<boolean>

    Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กิจกรรม

onAdded

browser.permissions.onAdded.addListener(
  callback: function,
)

เริ่มทำงานเมื่อส่วนขยายได้รับสิทธิ์ใหม่

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    (permissions: Permissions) => void

onRemoved

browser.permissions.onRemoved.addListener(
  callback: function,
)

เริ่มทำงานเมื่อนำสิทธิ์เข้าถึงออกจากส่วนขยาย

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    (permissions: Permissions) => void