App Flip สำหรับ Android

เมื่อติดตั้งใช้งาน OAuth 2.0 แล้ว คุณจะกำหนดค่า App Flip ที่ใช้ OAuth ได้ (ไม่บังคับ) ซึ่งจะช่วยให้ผู้ใช้ Android ลิงก์บัญชีในระบบการตรวจสอบสิทธิ์ของคุณกับบัญชี Google ได้รวดเร็วยิ่งขึ้น ส่วนต่อไปนี้จะอธิบายวิธีออกแบบและติดตั้งใช้งาน App Flip สำหรับการผสานรวม Cloud-to-cloud ใน Android

หลักเกณฑ์การออกแบบ

ส่วนนี้อธิบายข้อกำหนดและคำแนะนำในการออกแบบหน้าจอขอความยินยอมในการลิงก์บัญชี App Flip หลังจากที่ Google เรียกใช้แอปของคุณแล้ว แอปจะแสดงหน้าจอขอความยินยอมต่อผู้ใช้

ข้อกำหนด

1. คุณต้องมีข้อความการให้สิทธิ์ของ Google เช่น "เมื่อลิงก์แล้ว Google จะมีสิทธิ์ควบคุมอุปกรณ์ของคุณ"
2. คุณต้องแจ้งให้ผู้ใช้ทราบว่าบัญชีของผู้ใช้จะลิงก์กับ Google ไม่ใช่ผลิตภัณฑ์ Google ที่เฉพาะเจาะจง เช่น Google Home หรือ Google Assistant
3. คุณต้องระบุคำกระตุ้นให้ดำเนินการที่ชัดเจนในหน้าจอความยินยอม และใช้คำว่า "ยอมรับและลิงก์" สำหรับการดำเนินการลิงก์ เนื่องจาก ผู้ใช้ต้องเข้าใจว่าตนเองต้องแชร์ข้อมูลใดกับ Google เพื่อ ลิงก์บัญชี
4. คุณต้องระบุวิธีให้ผู้ใช้ย้อนกลับ ปฏิเสธ หรือยกเลิก หากผู้ใช้เลือกที่จะไม่ลิงก์ ใช้คำว่า "ยกเลิก" สำหรับการดำเนินการยกเลิก
5. คุณต้องใช้เวิร์กโฟลว์นี้: หลังจากคลิก "ยอมรับและลิงก์" คุณต้องแสดงการลิงก์สำเร็จและเปลี่ยนเส้นทางผู้ใช้กลับไปที่แอป Google Home โดยอัตโนมัติ ตอนนี้ผู้ใช้ควรเห็นอุปกรณ์ที่ลิงก์ในแอป Google Home พร้อมกับการดำเนินการของคุณ หลังจากคลิก "ยกเลิก" คุณควรเปลี่ยนเส้นทางผู้ใช้ กลับไปที่แอป Google Home

คำแนะนำ

เราขอแนะนำให้คุณทำดังนี้

1. แสดงนโยบายความเป็นส่วนตัวของ Google ระบุลิงก์ไปยังนโยบายความเป็นส่วนตัวของ Google ในหน้าจอขอความยินยอม

2. ข้อมูลที่จะแชร์ ใช้ภาษาที่ชัดเจนและกระชับเพื่อบอกผู้ใช้ว่า Google ต้องการข้อมูลใดของผู้ใช้และเพราะเหตุใด

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

4. ความสามารถในการเปลี่ยนบัญชีผู้ใช้ แนะนำวิธีให้ผู้ใช้เปลี่ยน บัญชี ซึ่งจะเป็นประโยชน์อย่างยิ่งหากผู้ใช้มีแนวโน้มที่จะมี หลายบัญชี

   • หากผู้ใช้ต้องปิดหน้าจอขอความยินยอมเพื่อเปลี่ยนบัญชี ให้ส่งข้อผิดพลาดที่กู้คืนได้ไปยัง Google เพื่อให้ผู้ใช้ลงชื่อเข้าใช้บัญชีที่ต้องการได้ด้วยการลิงก์ OAuth และโฟลว์โดยนัย

5. ใส่โลโก้ของคุณ แสดงโลโก้บริษัทในหน้าจอคำยินยอม ใช้หลักเกณฑ์ด้านสไตล์เพื่อวางโลโก้ หากต้องการแสดงโลโก้ของ Google ด้วย โปรดดูโลโก้และเครื่องหมายการค้า

ตั้งค่าสำหรับ App Flip ที่ใช้ OAuth

ส่วนต่อไปนี้จะอธิบายข้อกำหนดเบื้องต้นสำหรับ App Flip ที่ใช้ OAuth และวิธีกำหนดค่าโปรเจ็กต์ App Flip ใน Google Home Developer Console

สร้างการผสานรวมแบบ Cloud-to-cloud และตั้งค่าเซิร์ฟเวอร์ OAuth 2.0

ก่อนที่จะกำหนดค่า App Flip คุณต้องทำสิ่งต่อไปนี้

• ตั้งค่าเซิร์ฟเวอร์ OAuth 2.0 ดูข้อมูลเพิ่มเติมเกี่ยวกับการตั้งค่าเซิร์ฟเวอร์ OAuth ได้ที่ติดตั้งใช้งานเซิร์ฟเวอร์ OAuth 2.0
• สร้างการผสานรวมแบบระบบคลาวด์กับระบบคลาวด์ หากต้องการสร้างการผสานรวม ให้ทำตามวิธีการในหัวข้อสร้างการผสานรวมระบบคลาวด์กับคลาวด์

กำหนดค่า App Flip ใน Developer Console

ส่วนต่อไปนี้อธิบายวิธีกำหนดค่า App Flip ใน Developer Console

1. กรอกข้อมูลในช่องที่ต้องระบุ(*) ทั้งหมดในส่วนการลิงก์บัญชี (หากระบบไม่รองรับ App Flip ระบบจะใช้ OAuth ปกติเป็นตัวเลือกสำรอง)
2. ระบุ URL สำหรับ URL ของการดำเนินการบนระบบคลาวด์ ระบบจะใช้ URL ของการดำเนินการตามคำสั่งซื้อในระบบคลาวด์เพื่อประมวลผล Intent ของสมาร์ทโฮม ดูการดำเนินการในพื้นที่
3. ในส่วน App Flip (ไม่บังคับ) ให้เลือกแอป Android
4. กรอกข้อมูลในช่องต่อไปนี้
• รหัสแอปพลิเคชัน รหัสแอปพลิเคชันคือรหัสที่ไม่ซ้ำกันซึ่งคุณตั้งค่าไว้สำหรับแอป
• App Signature แอป Android ต้องได้รับการ "รับรอง" ด้วยใบรับรองคีย์สาธารณะก่อนจึงจะติดตั้งได้ ดูข้อมูลเกี่ยวกับการรับ App Signing ได้ที่หัวข้อการตรวจสอบสิทธิ์ไคลเอ็นต์
• Intent การให้สิทธิ์ ในช่องนี้ ให้ป้อนสตริงที่ระบุการดำเนินการตาม Intent
5. หากต้องการกำหนดค่าไคลเอ็นต์(ไม่บังคับ) ให้เพิ่มขอบเขต แล้วคลิกเพิ่มขอบเขตในส่วนขอบเขต (ไม่บังคับ)
6. หากไคลเอ็นต์กำหนดให้ต้องใช้ ให้เลือกให้ Google ส่งรหัสไคลเอ็นต์และรหัสลับผ่านส่วนหัวการตรวจสอบสิทธิ์พื้นฐานของ HTTP

ตอนนี้คุณสามารถไปยังส่วนถัดไปเพื่อติดตั้งใช้งาน App Flip ในแอป Android ได้แล้ว

ติดตั้งใช้งาน App Flip ในแอปที่มาพร้อมเครื่อง

หากต้องการใช้ App Flip คุณต้องแก้ไขรหัสการให้สิทธิ์ผู้ใช้ในแอปเพื่อยอมรับ Deep Link จาก Google

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

ในเอกสารนี้ คุณจะได้เรียนรู้วิธีแก้ไขแอป Android เพื่อรองรับ App Flip

ลองใช้ตัวอย่าง

แอปตัวอย่างการลิงก์ App Flip แสดงการผสานรวมการลิงก์บัญชีที่เข้ากันได้กับ App Flip บน Android คุณสามารถใช้แอปนี้เพื่อยืนยันวิธีตอบสนองต่อ Intent ของ App Flip ที่เข้ามาจากแอปบนอุปกรณ์เคลื่อนที่ของ Google

แอปตัวอย่างได้รับการกำหนดค่าล่วงหน้าให้ผสานรวมกับเครื่องมือทดสอบ App Flip สำหรับ Android ซึ่งคุณสามารถใช้เพื่อยืนยันการผสานรวมแอป Android กับ App Flip ก่อนกำหนดค่าการลิงก์บัญชีกับ Google แอปนี้จะจำลอง Intent ที่แอป Google บนอุปกรณ์เคลื่อนที่เรียกใช้เมื่อเปิดใช้ App Flip

วิธีการทำงาน

คุณต้องทำตามขั้นตอนต่อไปนี้เพื่อผสานรวม App Flip

1. แอป Google จะตรวจสอบว่าแอปของคุณติดตั้งอยู่ในอุปกรณ์หรือไม่โดยใช้ชื่อแพ็กเกจ
2. แอป Google ใช้การตรวจสอบลายเซ็นแพ็กเกจเพื่อตรวจสอบว่าแอปที่ติดตั้งเป็นแอปที่ถูกต้อง
3. แอป Google จะสร้าง Intent เพื่อเริ่มกิจกรรมที่กำหนดไว้ในแอปของคุณ Intent นี้มีข้อมูลเพิ่มเติมที่จำเป็นสำหรับการลิงก์ นอกจากนี้ ยังตรวจสอบว่าแอปของคุณรองรับ App Flip หรือไม่โดยการแก้ไข Intent นี้ผ่านเฟรมเวิร์ก Android
4. แอปของคุณจะตรวจสอบว่าคำขอมาจากแอป Google โดยแอปจะตรวจสอบลายเซ็นแพ็กเกจและรหัสไคลเอ็นต์ที่ระบุ
5. แอปของคุณจะขอรหัสการให้สิทธิ์จากเซิร์ฟเวอร์ OAuth 2.0 เมื่อสิ้นสุดขั้นตอนนี้ ระบบจะแสดงรหัสการให้สิทธิ์หรือข้อผิดพลาดไปยังแอป Google
6. แอป Google จะดึงผลลัพธ์และดำเนินการลิงก์บัญชีต่อ หากมีการระบุรหัสการให้สิทธิ์ การแลกเปลี่ยนโทเค็นจะเกิดขึ้นระหว่างเซิร์ฟเวอร์กับเซิร์ฟเวอร์ในลักษณะเดียวกับที่เกิดขึ้นในขั้นตอนการลิงก์ OAuth บนเบราว์เซอร์

แก้ไขแอป Android เพื่อรองรับ App Flip

หากต้องการรองรับ App Flip ให้ทำการเปลี่ยนแปลงโค้ดต่อไปนี้ในแอป Android

1. เพิ่ม <intent-filter> ลงในไฟล์ AndroidManifest.xml ด้วยสตริงการดำเนินการที่ตรงกับค่าที่คุณป้อนในช่อง App Flip Intent

   <activity android:name="AuthActivity">
     <!-- Handle the app flip intent -->
     <intent-filter>
       <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
       <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
   </activity>
   

2. ตรวจสอบลายเซ็นของแอปการโทร

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

   • ชื่อแพ็กเกจ: com.google.android.apps.chromecast.app
   • ใบรับรองสายเลือด SHA-256 เดิม: 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
   • ใบรับรอง SHA-256 ของ Play App Signing ที่หมุนเวียน: 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6

   และ

   • ชื่อแพ็กเกจ: com.google.android.googlequicksearchbox
   • ลายเซ็น: F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83

   คำขอลิงก์สมาร์ทโฮมจะเริ่มต้นโดยตรงจาก Google Home app (GHA) หากแอปพลิเคชันของคุณจำกัดผู้เรียกและก่อนหน้านี้อนุญาตเฉพาะแอป Google Search คุณต้องเพิ่ม com.google.android.apps.chromecast.app และใบรับรอง SHA-256 ลงในรายการที่อนุญาตเพื่อให้ App Flip ทำงานได้ต่อไป

   private fun verifyFingerprint(
       expectedPackage: String,
       expectedFingerprints: List<String>
   ): Boolean {
       val callingPackage = callingActivity?.packageName ?: return false
       if (callingPackage != expectedPackage) return false
       return expectedFingerprints.any { hex ->
           val sha256Bytes =
               hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
           packageManager.hasSigningCertificate(
               callingPackage,
               sha256Bytes,
               PackageManager.CERT_INPUT_SHA256
           )
       }
   }
   

3. ดึงรหัสไคลเอ็นต์จากพารามิเตอร์ Intent และยืนยันว่ารหัสไคลเอ็นต์ตรงกับค่าที่คาดไว้

   private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
   private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
   // Original lineage certificate (3D:7A...) and active rotated
   // Play App Signing certificate (5A:AD...)
   private val EXPECTED_FINGERPRINTS = listOf(
       "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
       "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
   )
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {
   
           // ...authorize the user...
       }
   }
   

4. เมื่อให้สิทธิ์เรียบร้อยแล้ว ให้ส่งรหัสการให้สิทธิ์ที่ได้กลับไปให้ Google

   // Successful result
   val data = Intent().apply {
       putExtra("AUTHORIZATION_CODE", authCode)
   }
   setResult(Activity.RESULT_OK, data)
   finish()
   

5. หากเกิดข้อผิดพลาด ให้แสดงผลลัพธ์ข้อผิดพลาดแทน

   // Error result
   val error = Intent().apply {
       putExtra("ERROR_TYPE", 1)
       putExtra("ERROR_CODE", 1)
       putExtra("ERROR_DESCRIPTION", "Invalid Request")
   }
   setResult(-2, error)
   finish()
   

เนื้อหาของ Intent การเปิดตัว

Intent ของ Android ที่เปิดแอปของคุณจะมีช่องต่อไปนี้

• CLIENT_ID (String): Google client_id ที่ลงทะเบียนไว้ในแอปของคุณ
• SCOPE (String[]): รายการขอบเขตที่ขอ
• REDIRECT_URI (String): URL เปลี่ยนเส้นทาง

เนื้อหาของข้อมูลการตอบกลับ

ข้อมูลที่ส่งกลับไปยังแอป Google จะตั้งค่าในแอปของคุณโดยการเรียกใช้ setResult() ข้อมูลนี้ประกอบด้วยรายการต่อไปนี้

• AUTHORIZATION_CODE (String): ค่ารหัสการให้สิทธิ์
• resultCode (int): สื่อสารความสำเร็จหรือความล้มเหลวของกระบวนการและใช้ค่าใดค่าหนึ่งต่อไปนี้
  • Activity.RESULT_OK: บ่งชี้ว่าสำเร็จ ระบบจะแสดงรหัสการให้สิทธิ์
  • Activity.RESULT_CANCELLED: ข้อผิดพลาดที่กู้คืนได้ สัญญาณที่บ่งบอกว่าผู้ใช้ยกเลิกกระบวนการ ในกรณีนี้ แอป Google จะพยายามลิงก์บัญชีอีกครั้งโดยใช้ URL การให้สิทธิ์
  • -2: บ่งบอกว่าเกิดข้อผิดพลาด ข้อผิดพลาดประเภทต่างๆ มีคำอธิบายดังต่อไปนี้
• ERROR_TYPE (int): ประเภทข้อผิดพลาด ซึ่งมีค่าใดค่าหนึ่งต่อไปนี้
  • 1: ข้อผิดพลาดที่กู้คืนได้: แอป Google จะพยายามลิงก์บัญชีโดยใช้ URL การให้สิทธิ์
  • 2: ข้อผิดพลาดที่กู้คืนไม่ได้: แอป Google ยกเลิกการลิงก์บัญชี
  • 3: พารามิเตอร์คำขอไม่ถูกต้องหรือขาดหายไป
• ERROR_CODE (int): จำนวนเต็มที่แสดงลักษณะของข้อผิดพลาด หากต้องการดูความหมายของรหัสข้อผิดพลาดแต่ละรายการ โปรดดูตารางรหัสข้อผิดพลาด

• ERROR_DESCRIPTION (String, ไม่บังคับ): ข้อความสถานะที่มนุษย์อ่านได้ซึ่งอธิบายข้อผิดพลาด

ต้องระบุค่าสำหรับ AUTHORIZATION_CODE เมื่อ resultCode == Activity.RESULT_OK ในกรณีอื่นๆ ทั้งหมด ค่าของ AUTHORIZATION_CODE ต้องเว้นว่างไว้ หาก resultCode == -2 ระบบจะคาดว่าค่า ERROR_TYPE จะได้รับการป้อนข้อมูล

ตารางรหัสข้อผิดพลาด

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

รหัสข้อผิดพลาด	ความหมาย	กู้คืนได้	ไม่สามารถเรียกคืนได้
1	INVALID_REQUEST	✔
2	NO_INTERNET_CONNECTION		✔
3	OFFLINE_MODE_ACTIVE	✔
4	CONNECTION_TIMEOUT	✔
5	INTERNAL_ERROR	✔
6	AUTHENTICATION_SERVICE_UNAVAILABLE		✔
8	CLIENT_VERIFICATION_FAILED	✔
9	INVALID_CLIENT	✔
10	INVALID_APP_ID	✔
11	INVALID_REQUEST	✔
12	AUTHENTICATION_SERVICE_UNKNOWN_ERROR		✔
13	AUTHENTICATION_DENIED_BY_USER		✔
14	CANCELLED_BY_USER		✔
15	FAILURE_OTHER		✔
16	USER_AUTHENTICATION_FAILED	✔

สำหรับรหัสข้อผิดพลาดทั้งหมด คุณต้องแสดงผลข้อผิดพลาดผ่าน setResult เพื่อให้แน่ใจว่ามีการเรียกใช้โฆษณาสำรองที่เหมาะสม

ทดสอบ App Flip ในอุปกรณ์

เมื่อสร้างการผสานรวมระบบคลาวด์กับระบบคลาวด์และกำหนดค่า App Flip ในคอนโซลและในแอปแล้ว คุณจะทดสอบ App Flip ในอุปกรณ์เคลื่อนที่ได้ คุณใช้แอป Google Home เพื่อทดสอบ App Flip ได้

หากต้องการทดสอบ App Flip จากแอป Google Home ให้ทำตามขั้นตอนต่อไปนี้

1. ไปที่ Developer Console แล้วเลือกโปรเจ็กต์
2. ไปที่ระบบที่เชื่อมต่อระหว่างระบบคลาวด์ > ทดสอบ
3. เรียกใช้ขั้นตอนการลิงก์บัญชีจากแอป Home โดยทำดังนี้
1. เปิด Google Home app (GHA)
2. คลิกปุ่ม +
3. คลิกตั้งค่าอุปกรณ์
4. คลิกหากมีรายการที่ตั้งค่าไว้แล้ว
5. เลือกการผสานรวมระบบคลาวด์กับระบบคลาวด์จากรายชื่อผู้ให้บริการ โดยจะมีคำนำหน้าว่า "[test]" ในรายการ เมื่อเลือกการผสานรวม [ทดสอบ] จากรายการ ระบบควรเปิดแอปของคุณ
6. ยืนยันว่าแอปเปิดขึ้นแล้วและเริ่มทดสอบขั้นตอนการให้สิทธิ์