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

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

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

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

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

คุณต้องเผยแพร่ไฟล์ 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"]
  }
}]

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

Dynamic App Link ใน Android 15 ขึ้นไปช่วยให้คุณใช้กฎการจับคู่ Deep Link ฝั่งเซิร์ฟเวอร์ที่ทำงานร่วมกับกฎที่คุณกำหนดไว้แบบคงที่ในไฟล์ Manifest ของแอปได้ ไฟล์ 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 ที่ตรงกันเปิดแอปของคุณ
  • ตัวอย่างนี้แสดงตัวอย่าง Matcher สำหรับเส้นทาง ("/"), Fragment ("#") และพารามิเตอร์การค้นหา ("?") รวมถึง Matcher ที่ยกเว้น ("exclude")
  • หากฟิลด์ใดๆ ในไฟล์มีรูปแบบไม่ถูกต้องหรือว่างเปล่า Android จะทิ้งกฎแบบไดนามิกและอุปกรณ์จะกลับไปใช้กฎที่กำหนดแบบคงที่ในไฟล์ Manifest ของแอป

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

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

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

  • การจับคู่เส้นทาง
    • แป้น: "/"
    • ค่า: สตริงเดียว นิพจน์ที่ตรงกันสำหรับเส้นทาง URL
  • การจับคู่ส่วนย่อย
    • แป้น: "#"
    • ค่า: สตริงเดียว นิพจน์ที่ตรงกันสำหรับส่วนย่อย 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 หลายรายการที่ประกาศในคำสั่งเดียว

ในกรณีเช่นนี้ 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 อื่นสำหรับบิลด์เวอร์ชันนักพัฒนาซอฟต์แวร์

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