เพิ่มตัวกรอง Intent สำหรับ App Link

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

1. เพิ่มตัวกรอง Intent อย่างน้อย 1 รายการลงในไฟล์ Manifest ของแอปที่ระบุโดเมนหรือ URL ของเว็บไซต์
2. เพิ่ม autoVerify="true"attribute ลงในองค์ประกอบตัวกรอง Intent ซึ่งจะส่งสัญญาณไปยังระบบว่าควรพยายามยืนยันสคีมาและโดเมนโฮสต์กับการกำหนดค่า assetlinks.json ของเว็บไซต์
3. ประกาศการเชื่อมโยงเว็บไซต์

ต่อไปนี้เป็นตัวอย่างของการประกาศ App Link ที่มีรูปแบบและโฮสต์ รวมถึง autoVerify="true"

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <!-- Make sure you explicitly set android:autoVerify to "true". -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- If a user clicks on a link that uses the "http" scheme, your
             app should be able to delegate that traffic to "https". -->
        <!-- Do not include other schemes, as this will prevent verification. -->
        <data android:scheme="http" />
        <data android:scheme="https" />

        <!-- Include one or more domains that should be verified. -->
        <data android:host="www.example.com" />
        <data android:host="*.example.com" />
    </intent-filter>
</activity>

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

• AutoVerify: ต้องระบุแอตทริบิวต์ android:autoVerify="true" สำหรับ App Links ซึ่งจะส่งสัญญาณไปยังระบบว่าควรพยายามยืนยัน การเชื่อมโยงระหว่างแอปกับสคีมาและโดเมนที่ระบุในแท็ก <data> เราขอแนะนำให้เพิ่ม autoVerify="true" ลงในตัวกรอง Intent ทุกรายการที่คุณต้องการให้ยืนยันได้
• องค์ประกอบข้อมูล: ตัวกรอง Intent ของ App Links แต่ละรายการต้องมีองค์ประกอบ <data> อย่างน้อย 1 รายการที่ระบุรูปแบบสคีมและโฮสต์ที่ตรงกับโดเมนเว็บไซต์ที่ยืนยันได้
• รูปแบบ: ตัวกรอง Intent ต้องมีองค์ประกอบ <data> สำหรับทั้งรูปแบบ http และ https

• โฮสต์: คุณสามารถเพิ่มองค์ประกอบ <data> เพื่อจับคู่กับโฮสต์อย่างน้อย 1 รายการได้ (ไม่บังคับ) ใช้ไวลด์การ์ด (*) เพื่อจับคู่โดเมนย่อยหลายรายการ (เช่น *.example.com) ระบบจะพยายามยืนยันโฮสต์แต่ละรายการกับไฟล์ assetlinks.json ในเว็บไซต์ของคุณ โปรดทราบว่าการกำหนดเส้นทางระดับเส้นทางควรจัดการโดยไฟล์ assetlinks.json (ดูส่วนแนวทางปฏิบัติแนะนำด้านล่าง)

• โฮสต์หลายรายการ: หากคุณประกาศโดเมนที่ฝากบริการหลายรายการ ระบบ (ใน Android 12 ขึ้นไป) จะพยายามยืนยันแต่ละรายการ หากโฮสต์ได้รับการยืนยัน แอปจะกลายเป็นเครื่องมือจัดการเริ่มต้นสำหรับลิงก์จากโฮสต์ที่ได้รับการยืนยันนั้น ใน Android 11 และต่ำกว่า การยืนยันจะไม่สําเร็จหากมีโฮสต์ที่ไม่สามารถยืนยันได้แม้เพียงโฮสต์เดียว

• ตัวกรอง Intent หลายรายการ: คุณต้องสร้างตัวกรองแยกต่างหากเมื่อต้องการประกาศ URL ที่ไม่ซ้ำกัน (เช่น ชุดค่าผสมที่เฉพาะเจาะจงของรูปแบบและโฮสต์) เนื่องจากองค์ประกอบ <data> หลายรายการในตัวกรอง Intent เดียวกันจะผสานรวมเข้าด้วยกันเพื่อพิจารณาตัวแปรทั้งหมดของแอตทริบิวต์ที่รวมกัน

ข้อควรพิจารณาสำหรับกฎตัวกรองไฟล์ Manifest

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

ด้วยเหตุนี้ เราขอแนะนำให้ใช้วิธีการต่อไปนี้

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

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

รองรับ App Link สำหรับโฮสต์หลายรายการ

ระบบต้องยืนยันโฮสต์ที่ระบุในองค์ประกอบข้อมูลของตัวกรอง Intent ของ URL ของแอปกับไฟล์ลิงก์เนื้อหาดิจิทัล (Digital Asset Links) ที่โฮสต์ในโดเมนเว็บที่เกี่ยวข้องในตัวกรอง Intent นั้นได้ หากการยืนยันไม่สำเร็จ ระบบจะกลับไปใช้ลักษณะการทำงานมาตรฐานเพื่อแก้ไข Intent ตามที่อธิบายไว้ในสร้าง Deep Link ไปยังเนื้อหาแอป อย่างไรก็ตาม แอปจะยังคง ได้รับการยืนยันเป็นตัวแฮนเดิลเริ่มต้นสำหรับรูปแบบ URL ใดก็ตามที่กำหนดไว้ใน ตัวกรอง Intent อื่นๆ ของแอป

ตัวอย่างเช่น แอปที่มีตัวกรอง Intent ต่อไปนี้จะผ่านการยืนยันเฉพาะ https://www.example.com หากพบไฟล์ assetlinks.json ที่ https://www.example.com/.well-known/assetlinks.json แต่ไม่พบที่ https://www.example.net/.well-known/assetlinks.json

<application>

  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name="SecondActivity">
    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

รองรับการลิงก์แอปสำหรับโดเมนย่อยหลายโดเมน

โปรโตคอลลิงก์เนื้อหาดิจิทัล (Digital Asset Links) จะถือว่าโดเมนย่อยในตัวกรอง Intent เป็นโฮสต์ที่ไม่ซ้ำกันและแยกต่างหาก ดังนั้น หากตัวกรอง Intent แสดงโฮสต์หลายรายการที่มีโดเมนย่อยต่างกัน คุณต้องเผยแพร่ assetlinks.json ที่ถูกต้องในแต่ละโดเมน ตัวอย่างเช่น ตัวกรอง Intent ต่อไปนี้มี www.example.com และ mobile.example.com เป็นโฮสต์ URL ของ Intent ที่ยอมรับ ดังนั้นจึงต้องเผยแพร่ assetlinks.json ที่ถูกต้องทั้งใน https://www.example.com/.well-known/assetlinks.json และ https://mobile.example.com/.well-known/assetlinks.json

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

หรือหากคุณประกาศชื่อโฮสต์ด้วยไวลด์การ์ด (เช่น *.example.com) คุณต้องเผยแพร่ไฟล์ assetlinks.json ที่ชื่อโฮสต์รูท (example.com) ตัวอย่างเช่น แอปที่มีตัวกรอง Intent ต่อไปนี้จะผ่านการยืนยันสำหรับชื่อย่อยของ example.com (เช่น foo.example.com) ตราบใดที่มีการเผยแพร่ไฟล์ assetlinks.json ที่ https://example.com/.well-known/assetlinks.json

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

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

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

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

ความเข้ากันได้แบบย้อนหลังของ App Link แบบไดนามิกสำหรับ Android 14 และต่ำกว่า

ฟีเจอร์ App Link แบบไดนามิก ซึ่งรวมถึงกฎการจับคู่ขั้นสูงใน assetlinks.json และการใช้ <uri-relative-filter-group> ได้รับการรองรับอย่างเต็มรูปแบบใน Android 15 (ระดับ API 35) ขึ้นไปเท่านั้น

ใน Android 14 (ระดับ API 34) และต่ำกว่า ระบบจะพิจารณาเฉพาะ scheme และ host ที่ประกาศไว้ในองค์ประกอบ <data> ของไฟล์ Manifest สำหรับการยืนยัน App Link เท่านั้น ระบบจะไม่ใช้กฎ การยกเว้น และการอัปเดตแบบไดนามิกที่เฉพาะเจาะจงเส้นทางจาก assetlinks.json

ซึ่งหมายความว่าหากไฟล์ Manifest ระบุเฉพาะ scheme และ host แอปอาจจับเส้นทางทั้งหมดสำหรับโดเมนที่ยืนยันแล้วใน Android 14 และต่ำกว่าโดยไม่คาดคิด ไม่ว่ากฎเฉพาะเส้นทางที่กำหนดไว้ใน assetlinks.json สำหรับ Android 15 ขึ้นไปจะเป็นอย่างไรก็ตาม

กลยุทธ์สำรองสำหรับ Android เวอร์ชันต่ำกว่าที่จะกำหนดค่าโดยไม่มี Deep Link

หากต้องการป้องกันไม่ให้แอปจัดการลิงก์ทั้งหมดสำหรับโดเมนใน Android 14 และต่ำกว่าเมื่อคุณตั้งใจจะใช้ App Link แบบไดนามิกสำหรับเส้นทางที่เฉพาะเจาะจงมากขึ้นใน Android 15 ขึ้นไป ให้รวมเส้นทางที่ไม่ตรงกันไว้ในตัวกรอง Intent ของไฟล์ Manifest เพิ่มองค์ประกอบ <data> ที่มีแอตทริบิวต์ android:path ซึ่งไม่น่าจะเป็นเส้นทางที่ถูกต้องสำหรับลิงก์ของคุณ วิธีนี้ช่วยให้มั่นใจได้ว่าตัวกรอง Intent จะไม่ตรงกับเส้นทางทั้งหมดในเวอร์ชันที่ต่ำกว่า

ตัวอย่าง

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="http" />
        <data android:scheme="https" />
        <data android:host="www.example.com" />

        <!-- Add a non-matching path for backward compatibility -->
        <data android:path="/no_match_for_older_android_versions" />

        <uri-relative-filter-group android:allow="true">
          <data android:pathPattern="/.*"/>
        </uri-relative-filter-group>
    </intent-filter>
</activity>

การเพิ่ม <data android:path="/no_match_for_older_android_versions" /> จะช่วยให้มั่นใจได้ว่าใน Android 14 และต่ำกว่า ตัวกรอง Intent นี้จะไม่ตรงกับลิงก์ขาเข้าใดๆ ขณะที่ยังคงอนุญาตให้ยืนยันโดเมนเพื่อใช้กับ Dynamic App Link ใน Android 15 ขึ้นไปตามกฎการจับคู่ขั้นสูงในกฎ assetlinks.json

การย้ายข้อมูล App Link ที่มีอยู่

หากคุณมี App Link ที่มีกฎเส้นทางที่เฉพาะเจาะจง (เช่น android:pathPrefix) ในไฟล์ Manifest อยู่แล้ว และต้องการเริ่มใช้ App Link แบบไดนามิกใน Android 15 ขึ้นไป คุณสามารถเพิ่มองค์ประกอบ <uri-relative-filter-group> ลงในตัวกรอง Intent ที่มีอยู่ได้โดยตรงอย่างปลอดภัย

เนื่องจาก Android 14 และเวอร์ชันที่ต่ำกว่าจะละเว้นองค์ประกอบ <uri-relative-filter-group> App Link ที่มีอยู่จึงยังคงทำงานเหมือนเดิมบนอุปกรณ์ที่ใช้ Android เวอร์ชันต่ำกว่า

อย่างไรก็ตาม คุณต้องพิจารณาอย่างรอบคอบว่า Android 15 ขึ้นไปประเมินการกำหนดค่า "แบบผสม" อย่างไร

• การกรอง 2 ชั้น: ใน Android 15 ขึ้นไป ระบบจะประเมินตัวกรอง Intent เป็นแบบรวม URL จะผ่านการตรวจสอบไฟล์ Manifest หากเป็นไปตามแท็ก <data> แบบคงที่เดิมหรือกฎแบบกว้างใน <uri-relative-filter-group> เมื่อ URL ผ่านการตรวจสอบไฟล์ Manifest เบื้องต้นนี้แล้ว ระบบจะใช้กฎแบบไดนามิกที่กำหนดไว้ในไฟล์ assetlinks.json เป็นการกรองแบบละเอียดชั้นที่ 2 ซึ่งหมายความว่ากฎ JSON ฝั่งเซิร์ฟเวอร์จะเป็นตัวกำหนดว่า URL ที่ตรงกันรายการใดจะเปิดแอปจริงๆ

ตัวอย่างการกำหนดค่าแบบผสม

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="https" />
    <data android:host="www.example.com" />

    <!-- Legacy rule: Android 14 and lower use this. Android 15 and higher
         also use this. -->
    <data android:pathPrefix="/store" />

    <!--
      Dynamic rule: Android 14 and lower ignore this. Android 15 and higher
      evaluate this as a union between all paths and the configuration
      specified in the assetlinks.json file. Make sure to apply further
      refinements in the assetlinks.json file to prevent all URL paths from
      opening in the app.
    -->
    <uri-relative-filter-group android:allow="true">
        <data android:pathPrefix="/" />
    </uri-relative-filter-group>
</intent-filter>