chrome.permissions

คำอธิบาย

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

ภาพรวม

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

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

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

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

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

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

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

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

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

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

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

ประโยชน์ของสิทธิ์ที่ไม่บังคับมีดังนี้

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

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

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

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

หากต้องการขอโฮสต์ที่คุณค้นพบขณะรันไทม์เท่านั้น ให้ใส่ "https://*/*" ในช่อง optional_host_permissions ของส่วนขยาย การดำเนินการนี้ช่วยให้คุณระบุต้นทางใน Permissions.origins ใดก็ตามได้ก็ต่อเมื่อมีต้นทางที่ตรงกัน สคีม

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

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

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

chrome.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() จะเพิ่มสิทธิ์กลับเข้ามาโดยไม่ต้องแจ้งผู้ใช้

chrome.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

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

  • ต้นทาง

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

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

  • สิทธิ์

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

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

เมธอด

contains()

สัญญา
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

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

พารามิเตอร์

  • สิทธิ์
  • Callback

    ไม่บังคับ

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

    (result: boolean) => void

    • ผลลัพธ์

      boolean

      เป็นจริงหากส่วนขยายมีสิทธิ์ที่ระบุ หากต้นทางระบุว่าเป็นทั้งสิทธิ์ที่ไม่บังคับและรูปแบบการจับคู่สคริปต์เนื้อหา ต้นทางจะแสดงผล false เว้นแต่จะได้รับสิทธิ์ทั้ง 2 รายการ

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

  • Promise<boolean>

    Chrome 96 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

getAll()

สัญญา
chrome.permissions.getAll(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (permissions: Permissions) => void

    • สิทธิ์

      สิทธิ์ที่ใช้งานอยู่ของส่วนขยาย โปรดทราบว่าพร็อพเพอร์ตี้ origins จะมีต้นทางที่ได้รับอนุญาตจากคีย์ permissions และ optional_permissions ในไฟล์ Manifest และต้นทางที่เชื่อมโยงกับสคริปต์เนื้อหา

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

  • Promise<Permissions>

    Chrome 96 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

remove()

สัญญา
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

นำสิทธิ์เข้าถึงสิทธิ์ที่ระบุออก หากพบปัญหาในการนำสิทธิ์ออก ระบบจะตั้งค่า runtime.lastError

พารามิเตอร์

  • สิทธิ์
  • Callback

    ไม่บังคับ

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

    (removed: boolean) => void

    • ลบแล้ว

      boolean

      เป็นจริงหากสิทธิ์ถูกนำออก

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

  • Promise<boolean>

    Chrome 96 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

request()

สัญญา
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

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

พารามิเตอร์

  • สิทธิ์
  • Callback

    ไม่บังคับ

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

    (granted: boolean) => void

    • อนุญาต

      boolean

      จริงหากผู้ใช้ให้สิทธิ์ที่ระบุ

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

  • Promise<boolean>

    Chrome 96 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

กิจกรรม

onAdded

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (permissions: Permissions) => void

onRemoved

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (permissions: Permissions) => void