กำหนดค่าการเชื่อมโยงเว็บไซต์และกฎแบบไดนามิก

หากต้องการรองรับ App Link คุณต้องสร้างไฟล์ JSON ของลิงก์เนื้อหาดิจิทัล ที่ชื่อ assetlinks.json และเผยแพร่ในตำแหน่งที่รู้จักกันดีบน เว็บไซต์ ไฟล์นี้จะประกาศต่อสาธารณะว่าแอปใดได้รับอนุญาตให้จัดการลิงก์สำหรับโดเมนของคุณ และอุปกรณ์ Android จะดึงข้อมูลไฟล์นี้จากเซิร์ฟเวอร์ของคุณเพื่อยืนยัน Deep Link

สำหรับ App Link แบบไดนามิกใน Android 15 ขึ้นไป ไฟล์ assetlinks.json ยังเป็น ที่ที่คุณกำหนดค่ากฎแบบไดนามิกเช่น ตัวจับคู่รูปแบบ สำหรับเส้นทาง ส่วนย่อย และพารามิเตอร์การค้นหา อุปกรณ์ Android ที่ใช้ Android 15 (ระดับ API 35) ขึ้นไปซึ่งติดตั้งบริการของ Google จะดึงข้อมูลไฟล์นี้เป็นระยะๆ และผสานการกำหนดค่าแบบไดนามิกกับการกำหนดค่าแบบคงที่ในไฟล์ Manifest ของแอป

คู่มือนี้จะอธิบายวิธีเตรียมไฟล์ assetlinks.json และเผยแพร่ในเว็บไซต์ หากต้องการ คุณสามารถสร้างไฟล์ assetlinks.json จากเครื่องมือ Play Deep Links หรือผู้ช่วย App Link ของ Android Studio ดูข้อมูลเพิ่มเติมได้ที่ เครื่องมือสำหรับนักพัฒนา App Link

ประกาศการเชื่อมโยงเว็บไซต์

คุณต้องเผยแพร่ไฟล์ JSON ของลิงก์เนื้อหาดิจิทัล (Digital Asset Links) ใน เว็บไซต์เพื่อระบุแอป Android ที่เชื่อมโยงกับเว็บไซต์และ ยืนยัน Intent ของ URL ของแอป ไฟล์ JSON จะใช้ฟิลด์ต่อไปนี้เพื่อระบุแอปที่เชื่อมโยง

• package_name: รหัสแอปพลิเคชันที่ประกาศไว้ในbuild.gradle ไฟล์ของแอป
• sha256_cert_fingerprints: ลายนิ้วมือ SHA256 ในใบรับรองการลงนามของแอป คุณสามารถใช้คำสั่งต่อไปนี้เพื่อสร้างลายนิ้วมือโดยใช้ Keytool ของ Java

keytool -list -v -keystore my-release-key.keystore

• ฟิลด์นี้รองรับลายนิ้วมือหลายรายการ ซึ่งสามารถใช้เพื่อรองรับแอปเวอร์ชันต่างๆ เช่น บิลด์สำหรับดีบักและบิลด์สำหรับใช้งานจริง หากคุณ ใช้ Play App Signing สำหรับแอป ลายนิ้วมือของใบรับรอง ที่สร้างขึ้นโดยการเรียกใช้ keytool ในเครื่องมักจะไม่ตรงกับ ลายนิ้วมือในอุปกรณ์ของผู้ใช้ คุณสามารถตรวจสอบว่าคุณใช้ Play App Signing สำหรับแอปหรือไม่ในบัญชีนักพัฒนาแอป Play Console ในส่วน Release > Setup > App signing หากใช้ คุณจะเห็นข้อมูลโค้ด JSON ของ ลิงก์เนื้อหาดิจิทัล (Digital Asset Links) ที่ถูกต้องสำหรับแอปในหน้าเดียวกันด้วย

ตัวอย่างไฟล์ assetlinks.json ต่อไปนี้ให้สิทธิ์ในการเปิดลิงก์แก่แอป Android com.example

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

เชื่อมโยงเว็บไซต์กับแอปหลายแอป

เว็บไซต์สามารถประกาศการเชื่อมโยงกับแอปหลายแอปภายในไฟล์ assetlinks.json เดียวกัน รายการไฟล์ต่อไปนี้แสดงตัวอย่างไฟล์คำสั่งที่ประกาศการเชื่อมโยงกับแอป 2 แอปแยกกัน และอยู่ใน https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

แอปต่างๆ อาจจัดการลิงก์สำหรับทรัพยากรต่างๆ ภายใต้เว็บโฮสต์เดียวกัน เช่น app1 อาจประกาศตัวกรอง Intent สำหรับ https://example.com/articles และ app2 อาจประกาศตัวกรอง Intent สำหรับ https://example.com/videos

หมายเหตุ: แอปหลายแอปที่เชื่อมโยงกับโดเมนอาจลงนามด้วยใบรับรองเดียวกันหรือ ต่างกัน

เชื่อมโยงเว็บไซต์หลายเว็บไซต์กับแอปเดียว

เว็บไซต์หลายเว็บไซต์สามารถประกาศการเชื่อมโยงกับแอปเดียวกันในไฟล์ assetlinks.json ของตนเอง รายการไฟล์ต่อไปนี้แสดงตัวอย่างวิธีประกาศการเชื่อมโยงของ example.com และ example.net กับ app1 ข้อมูลแรกแสดงการเชื่อมโยงของ example.com กับ app1

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

ข้อมูลถัดไปแสดงการเชื่อมโยงของ example.net กับ app1 มีเพียงตำแหน่งที่โฮสต์ไฟล์เหล่านี้เท่านั้นที่แตกต่างกัน (.com และ .net)

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

กำหนดค่ากฎแบบไดนามิก

App Link แบบไดนามิกใน Android 15 ขึ้นไปช่วยให้คุณใช้กฎการจับคู่ Deep Link ฝั่งเซิร์ฟเวอร์ที่ทำงานร่วมกับกฎที่คุณกำหนดแบบคงที่ในไฟล์ Manifest ของแอปได้ ไฟล์ assetlinks.json เป็นที่ที่คุณกำหนดกฎแบบไดนามิก การรวมกฎแบบไดนามิกไว้ในไฟล์ `assetlinks.json` เป็นตัวเลือก

อุปกรณ์ Android ที่ใช้ Android 15 (ระดับ API 35) ขึ้นไปซึ่งติดตั้งบริการของ Google จะดึงข้อมูลไฟล์นี้จากเซิร์ฟเวอร์ของคุณเป็นระยะๆ และผสานการกำหนดค่ากฎแบบไดนามิกกับการกำหนดค่าแบบคงที่ในไฟล์ Manifest ของแอป ตัวอย่างต่อไปนี้แสดงไฟล์ assetlinks.json ที่มีกฎแบบไดนามิก

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

ประเด็นสำคัญเกี่ยวกับโค้ด

• App Link แบบไดนามิกเพิ่มส่วนขยายความสัมพันธ์ของลิงก์เนื้อหาดิจิทัล (Digital Asset Links) ใหม่ที่เรียกว่า dynamic_app_link_components ซึ่งเป็นที่ที่คุณกำหนดค่ากฎแบบไดนามิก
• กฎแบบไดนามิกสามารถมีตัวจับคู่รูปแบบสำหรับเส้นทาง ส่วนย่อย และพารามิเตอร์การค้นหา
• นอกจากนี้ คุณยังทำเครื่องหมายตัวจับคู่รูปแบบใดก็ได้เป็นตัวจับคู่ที่ยกเว้น เพื่อไม่ให้ URL ที่ตรงกันเปิดแอป
• ตัวอย่างนี้แสดงตัวอย่างตัวจับคู่สำหรับเส้นทาง ("/"), ส่วนย่อย ("#"), และพารามิเตอร์การค้นหา ("?") รวมถึงตัวจับคู่ที่ยกเว้น ("exclude")
• หากฟิลด์ใดๆ ในไฟล์มีรูปแบบไม่ถูกต้องหรือว่างเปล่า Android จะทิ้งกฎแบบไดนามิกและอุปกรณ์จะกลับไปใช้กฎที่กำหนดแบบคงที่ในไฟล์ Manifest ของแอป

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

ประกาศกฎแบบไดนามิก

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

• การจับคู่เส้นทาง
  • คีย์: "/"
  • ค่า: สตริงเดียว, นิพจน์การจับคู่สำหรับเส้นทาง URL
• การจับคู่ Fragment
  • คีย์: "#"
  • ค่า: สตริงเดียว, นิพจน์การจับคู่สำหรับส่วนย่อย URL
• การจับคู่พารามิเตอร์การค้นหา
  • คีย์: "?"
  • ค่า: พจนานุกรมเพื่อจับคู่คู่คีย์/ค่าในพารามิเตอร์การค้นหาของ URL
  • เช่น พจนานุกรม {"?", {"dl": "*", "in_app":"true"} จะจับคู่ สตริงการค้นหา "?in_app=true&dl=abc"
  • ลำดับของคู่คีย์/ค่าในพจนานุกรมไม่จำเป็นต้องตรงกับลำดับของคู่ในสตริงการค้นหา นอกจากนี้ พจนานุกรมไม่จำเป็นต้องจับคู่คู่คีย์/ค่าทั้งหมดในสตริงการค้นหา แต่ต้องพบการจับคู่สำหรับรายการพจนานุกรมทุกรายการ
  • เช่น พจนานุกรมจะจับคู่สตริงการค้นหา "?lang=en&in_app=true&tz=pst&dl=abc" ด้วย แต่จะไม่จับคู่สตริงการค้นหา "?lang=en&tz=pst&dl=abc"
• ยกเว้น
  • คีย์: "exclude"
  • ค่า: ค่าจริง/เท็จที่เป็นตัวเลือกสำหรับแต่ละกฎที่กำหนดไว้ใน dynamic_app_link_components (ดูตัวอย่าง)

คุณสามารถใช้อักขระพิเศษต่อไปนี้ในตัวจับคู่รูปแบบ

• "*" จะจับคู่อักขระ 0 ตัวขึ้นไปจนกว่าจะพบอักขระหลังไวลด์การ์ดในรูปแบบในสตริงที่ตรงกัน
• "?" จะจับคู่อักขระตัวเดียว
• "?*" จะจับคู่อักขระ 1 ตัวขึ้นไป

ค่าไม่มีข้อจำกัดด้านอักขระอื่นๆ

จัดลำดับกฎแบบไดนามิก

ลำดับที่ประกาศกฎมีความสำคัญ Android จะประเมินกฎแต่ละข้อตามลำดับจนกว่าจะพบรายการที่ตรงกัน

ตัวอย่างต่อไปนี้แสดงวิธีที่การจัดลำดับอาจส่งผลต่อการจัดการ กฎแรกจะจับคู่เส้นทางทั้งหมด ("*") แต่ยกเว้นการจับคู่ (exclude: true) ซึ่งหมายความว่าจะยกเว้น URL ทั้งหมดไม่ให้เปิดแอป ในกรณีนี้ ระบบจะไม่ประเมินกฎที่ 2 ที่อนุญาต "/path1" เลย

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

อย่างไรก็ตาม ในตัวอย่างถัดไป กฎ "/path1" จะประกาศก่อน ดังนั้นระบบจะประเมินกฎนี้ก่อนและจะเปิดแอปสำหรับ URL ที่ตรงกับ "/path1" กฎที่ 2 ที่ยกเว้น URL ทั้งหมดไม่ให้เปิดแอปจะได้รับการประเมินเป็นลำดับที่ 2 แต่จะประเมินก็ต่อเมื่อกฎแรกไม่ตรงกัน

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

หากไม่พบรายการที่ตรงกันในรายการคอมโพเนนต์ที่ประกาศไว้ URL จะไม่เปิดแอป ในตัวอย่างต่อไปนี้ ไม่มีเส้นทางใดที่ตรงกับ "/path3" ดังนั้นอุปกรณ์จะถือว่าเส้นทางนี้เป็นเส้นทางที่ยกเว้น

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

ลักษณะการทำงานนี้มีความสำคัญหากคุณต้องการให้ dynamic_app_link_components ยกเว้นเฉพาะบางส่วนของ URL แต่ให้ส่วนอื่นๆ ทั้งหมด ในตัวอย่างต่อไปนี้ การละเว้นกฎสุดท้ายเพื่ออนุญาตเส้นทางที่เหลือทั้งหมดจะหมายความว่า URL ทั้งหมดจะถูกยกเว้นจากแอป

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

กำหนดขอบเขตกฎแบบไดนามิกอย่างเหมาะสม

เมื่อกำหนดกฎฝั่งเซิร์ฟเวอร์เพื่อใช้กับ App Link แบบไดนามิกใน Android 15 ขึ้นไป คุณต้องกำหนดขอบเขตกฎอย่างเหมาะสมเพื่อให้กฎทำงานร่วมกับและเสริมตัวกรอง Intent แบบคงที่ที่ประกาศไว้ในไฟล์ Manifest ของแอป

กฎแบบไดนามิกที่ประกาศไว้ในไฟล์ assetlinks.json สามารถระบุกฎสำหรับโฮสต์ที่คุณประกาศไว้ในไฟล์ AndroidManifest.xml ของแอปเท่านั้น กฎแบบไดนามิกไม่สามารถขยายขอบเขตของกฎ URL ที่คุณประกาศแบบคงที่ในไฟล์ Manifest ของแอป

ด้วยเหตุนี้ เราจึงแนะนำให้ใช้แนวทางนี้กับกฎแบบไดนามิกและกฎแบบคงที่

• ในไฟล์ Manifest ของแอป ให้ตั้งกฎที่มีขอบเขตกว้างที่สุดเท่าที่จะเป็นไปได้ เช่น การประกาศเฉพาะสคีมและโดเมน
• ใช้กฎแบบไดนามิกฝั่งเซิร์ฟเวอร์เพื่อการปรับแต่งเพิ่มเติม เช่น การกำหนดเส้นทางระดับเส้นทาง

การกำหนดค่าที่เหมาะสมนี้จะช่วยให้คุณเพิ่มเส้นทาง App Link ใหม่แบบไดนามิกในไฟล์ assetlinks.json ได้ตามต้องการ โดยมั่นใจได้ว่าเส้นทางเหล่านั้นจะอยู่ในขอบเขตกว้างที่คุณตั้งไว้ในไฟล์ Manifest ของแอป

ประกาศ dynamic_app_link_components เพียงครั้งเดียว

หากต้องการจัดการกฎอย่างเหมาะสม ให้ประกาศออบเจ็กต์ dynamic_app_link_components เพียงรายการเดียวในคำสั่งสำหรับเว็บไซต์ ความสัมพันธ์ และแอปที่ระบุ

• มองหาคำสั่งหลายรายการสำหรับเว็บไซต์ ความสัมพันธ์ และแอปเดียวกันที่ประกาศออบเจ็กต์ dynamic_app_link_components
• มองหาออบเจ็กต์ dynamic_app_link_components หลายรายการที่ประกาศไว้ในคำสั่งเดียว

ในกรณีเช่นนี้ Android ไม่รับประกันว่าจะใช้การกำหนดค่ากฎแบบไดนามิกใด

ความเข้ากันได้ของกฎแบบไดนามิกกับการกำหนดค่า App Link ก่อนหน้า

หากคุณรองรับ App Link อยู่แล้ว คุณสามารถเพิ่มการรองรับ App Link แบบไดนามิกได้โดยตรงในไฟล์ assetlinks.json ที่มีอยู่ ฟิลด์ความสัมพันธ์สำหรับการยืนยัน App Link จะยังคงเหมือนเดิม และคุณสามารถเพิ่มฟิลด์ส่วนขยายความสัมพันธ์ใหม่สำหรับกฎแบบไดนามิกได้โดยไม่ต้องทำการเปลี่ยนแปลงอื่นๆ

อุปกรณ์ Android ที่ใช้ Android 14 (ระดับ API 34 หรือต่ำกว่า) จะไม่สนใจฟิลด์ส่วนขยายความสัมพันธ์ใหม่สำหรับกฎแบบไดนามิก ในขณะที่อุปกรณ์ที่ใช้ Android 15 ขึ้นไปจะผสานกฎเหล่านั้นกับกฎที่กำหนดไว้ในไฟล์ Manifest

เผยแพร่ไฟล์การยืนยัน JSON

คุณต้องเผยแพร่ไฟล์การยืนยัน JSON ในตำแหน่งต่อไปนี้

https://domain.name/.well-known/assetlinks.json

ตรวจสอบสิ่งต่อไปนี้

• ไฟล์ assetlinks.json จะแสดงด้วยประเภทเนื้อหา application/json
• ไฟล์ assetlinks.json ต้องเข้าถึงได้ผ่านการเชื่อมต่อ HTTPS ไม่ว่าตัวกรอง Intent ของแอปจะประกาศ HTTPS เป็นรูปแบบข้อมูลหรือไม่ก็ตาม
• ไฟล์ assetlinks.json ต้องเข้าถึงได้โดยไม่มีการเปลี่ยนเส้นทาง (ไม่มีการเปลี่ยนเส้นทาง 301 หรือ 302)
• หาก App Link รองรับโดเมนโฮสต์หลายโดเมน คุณต้องเผยแพร่ไฟล์ assetlinks.json ในแต่ละโดเมน ดู การรองรับการลิงก์แอปสำหรับ โฮสต์หลายรายการ
• อย่าเผยแพร่แอปด้วย URL ทดสอบในไฟล์ Manifest ที่สาธารณะอาจเข้าถึงไม่ได้ (เช่น URL ที่เข้าถึงได้ด้วย VPN เท่านั้น) วิธีแก้ปัญหาในกรณีเช่นนี้คือการกำหนดค่าบิลด์ย่อยเพื่อสร้างไฟล์ Manifest ที่แตกต่างกันสำหรับบิลด์สำหรับนักพัฒนาแอป

ดูคำแนะนำที่เกี่ยวข้องต่อไปนี้

• การสร้างรายการคำสั่ง
• ผู้ช่วย App Link ใน Android Studio
• เครื่องมือสำหรับนักพัฒนา App Link