אפליקציית 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, אפשר לעיין במאמר בנושא לוגו וסימנים מסחריים.

באיור הזה מוצגת דוגמה למסך בקשת הסכמה עם הסברים על הדרישות וההמלצות שצריך לפעול לפיהן כשמעצבים מסך בקשת הסכמה מהמשתמש.
איור 1: הנחיות לעיצוב מסך הסכמה לקישור חשבון.

הגדרה של App Flip מבוסס-OAuth

בקטעים הבאים מוסבר מהן הדרישות המוקדמות לקישור אפליקציות שמבוסס על OAuth, ואיך להגדיר את פרויקט קישור האפליקציות ב-Google Home Developer Console.

יצירת שילוב בין שירותי ענן והגדרת שרת OAuth 2.0

לפני שמגדירים את App Flip, צריך לבצע את הפעולות הבאות:

הגדרת קישור אפליקציות ב-Developer Console

בקטע הבא מוסבר איך להגדיר את קישור אפליקציות ב-Developer Console.

  1. ממלאים את כל שדות החובה(*) בקטע קישור חשבונות. (אם אין תמיכה בקישור אפליקציות, המערכת משתמשת ב-OAuth רגיל כגיבוי).
  2. מזינים כתובת URL בשדה Cloud fulfillment URL. כתובת ה-URL למילוי בקשות בענן משמשת לעיבוד ה-intents של הבית החכם. בודקים את מילוי הבקשות המקומי.
  3. בקטע קישור אפליקציות (אופציונלי), מסמנים את האפשרות אפליקציה ל-Android.
  4. ממלאים את השדות הבאים:
    • מזהה האפליקציה. מזהה האפליקציה הוא מזהה ייחודי שאתם מגדירים לאפליקציה.
    • חתימת האפליקציה. כדי להתקין אפליקציות ל-Android, צריך "לחתום" עליהן באמצעות אישור של מפתח ציבורי. כדי לקבל את חתימת האפליקציה, קראו את המאמר אימות הלקוח.
    • כוונת הרשאה. בשדה הזה, מזינים מחרוזת שמציינת את פעולת ה-Intent.
  5. אם רוצים להגדיר את הלקוח, מוסיפים היקפים ולוחצים על Add scope בקטע Scopes(s) (optional).
  6. אם הלקוח דורש זאת, בוחרים באפשרות Have Google transmit Client ID and secret via HTTP basic auth header.

עכשיו אפשר להמשיך לקטע הבא כדי להטמיע את App Flip באפליקציית Android.

הטמעה של App Flip באפליקציות נייטיב

כדי להטמיע את App Flip, צריך לשנות את קוד הרשאת המשתמש באפליקציה כך שיקבל קישור עומק מ-Google.

קישור אפליקציות שמבוסס על OAuth מוסיף את אפליקציית Android לתהליך הקישור של חשבון Google. בתהליך קישור חשבונות רגיל, המשתמש צריך להזין את פרטי הכניסה שלו בדפדפן. השימוש בקישור אפליקציות דוחה את כניסת המשתמש לאפליקציה ל-Android, וכך מאפשר לכם לנצל את ההרשאות הקיימות. אם המשתמש מחובר לאפליקציה, הוא לא צריך להזין מחדש את פרטי הכניסה כדי לקשר את החשבון. כדי להטמיע את התכונה "קישור אפליקציות" באפליקציה ל-Android, צריך לבצע רק כמה שינויים קלים בקוד.

במאמר הזה מוסבר איך לשנות את אפליקציית Android כדי לתמוך בקישור אפליקציות.

דוגמה לניסיון

האפליקציה לדוגמה לקישור אפליקציות מדגימה שילוב של קישור חשבונות שתואם לקישור אפליקציות ב-Android. אתם יכולים להשתמש באפליקציה הזו כדי לבדוק איך להגיב ל-intent נכנס של קישור אפליקציות מאפליקציות Google לנייד.

האפליקציה לדוגמה מוגדרת מראש לשילוב עם כלי הבדיקה של קישור אפליקציות ל-Android. אתם יכולים להשתמש בכלי הזה כדי לאמת את השילוב של אפליקציית Android עם קישור אפליקציות לפני שאתם מגדירים את קישור החשבון ל-Google. האפליקציה הזו מדמה את ה-intent שמופעל על ידי אפליקציות Google לנייד כשקישור האפליקציות מופעל.

איך זה עובד

כדי לבצע שילוב של קישור אפליקציות, צריך לבצע את השלבים הבאים:

  1. אפליקציית Google בודקת אם האפליקציה מותקנת במכשיר באמצעות שם החבילה שלה.
  2. אפליקציית Google משתמשת בבדיקת חתימת חבילה כדי לאמת שהאפליקציה המותקנת היא האפליקציה הנכונה.
  3. אפליקציית Google יוצרת Intent כדי להתחיל פעילות ייעודית באפליקציה שלכם. ה-Intent הזה כולל נתונים נוספים שנדרשים לקישור. בנוסף, היא בודקת אם האפליקציה תומכת בקישור אפליקציות על ידי פתרון ה-Intent הזה באמצעות Android framework.
  4. האפליקציה מאמתת שהבקשה מגיעה מאפליקציית Google. לשם כך, האפליקציה בודקת את החתימה של החבילה ואת מזהה הלקוח שסופק.
  5. האפליקציה מבקשת קוד הרשאה משרת OAuth 2.0. בסוף התהליך הזה, המערכת מחזירה לאפליקציית Google קוד הרשאה או שגיאה.
  6. אפליקציית Google מאחזרת את התוצאה וממשיכה בתהליך קישור החשבונות. אם מסופק קוד הרשאה, החלפת הטוקנים מתבצעת משרת לשרת, באותו אופן שבו היא מתבצעת בתהליך הקישור של OAuth שמבוסס על דפדפן.

שינוי אפליקציית Android כדי לתמוך ב-App Flip

כדי לתמוך בקישור אפליקציות, צריך לבצע את השינויים הבאים בקוד של אפליקציית Android:

  1. מוסיפים <intent-filter> לקובץ AndroidManifest.xml עם מחרוזת פעולה שתואמת לערך שהזנתם בשדה 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 וחיפוש Google, צריך להוסיף את שמות החבילות והחתימות שלהן:

    • שם החבילה: 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 שעבר רוטציה: 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, אתם צריכים להוסיף את com.google.android.apps.chromecast.app ואת אישורי ה-SHA-256 שלה לרשימת ההיתרים כדי שקישור האפליקציות ימשיך לפעול.

    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 במכשיר

אחרי שיצרתם שילוב בין שירותי ענן והגדרתם את קישור אפליקציות במסוף ובאפליקציה, אתם יכולים לבדוק את קישור אפליקציות במכשיר הנייד. אתם יכולים להשתמש באפליקציית Google Home כדי לבדוק את קישור אפליקציות.

כדי לבדוק את App Flip באפליקציית Google Home, צריך לפעול לפי השלבים הבאים:

  1. נכנסים אל Developer Console ובוחרים את הפרויקט.
  2. עוברים אל Cloud-to-cloud > Test.
  3. מפעילים את תהליך קישור החשבון מאפליקציית Home:
    1. פותחים את Google Home app (GHA).
    2. לוחצים על הכפתור +.
    3. לוחצים על הגדרת המכשיר.
    4. לוחצים על כבר הגדרת משהו?
    5. בוחרים את השילוב בין שירותי הענן מרשימת הספקים. הוא יופיע ברשימה עם הקידומת "[test]". כשבוחרים את השילוב [למטרות בדיקה] מהרשימה, האפליקציה אמורה להיפתח.
    6. מוודאים שהאפליקציה הופעלה ומתחילים לבדוק את תהליך ההרשאה.
הקודם
יצירת שילוב בין עננים
הבא
iOS