היפוך האפליקציה ל-Android

אחרי שהטמעת את OAuth 2.0 אפשר להגדיר את App Flip מבוססת-ה-OAuth, כדי לאפשר למשתמשי Android לקשר במהירות רבה יותר את החשבונות שלהם במערכת האימות לחשבונות Google שלהם. בקטעים הבאים מוסבר איך לעצב וליישם את App Flip עבור הפעולה smart home שלכם.

הנחיות עיצוב

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

דרישות

1. עליך להודיע שהחשבון של המשתמש מקושר ל-Google, לא למוצר ספציפי של Google, כגון Google Home או Google Assistant.

המלצות

מומלץ לבצע את הפעולות הבאות:

1. להצגת מדיניות הפרטיות של Google. הוסיפו קישור למדיניות הפרטיות של Google במסך ההסכמה.

2. הנתונים לשיתוף. השתמש בשפה ברורה ותמציתית כדי לספר למשתמשים אילו נתונים הם צריכים ולמה.

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

4. יכולת לבטל. למשתמשים יש אפשרות לחזור או לבטל את המינוי, אם הם בוחרים שלא לבצע את הקישור.

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

6. יכולת לשנות את חשבון המשתמש. להציע למשתמשים שיטה להחלפת חשבונות. זה שימושי במיוחד אם למשתמשים יש בדרך כלל מספר חשבונות.

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

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

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

בקטעים הבאים מתוארות הדרישות המוקדמות ל-App Flip מבוסס OAuth, ומוסבר איך להגדיר את הפרויקט של App Flip במסוף הפעולות.

יצירת פעולה בבית חכם והגדרת שרת OAuth 2.0

לפני שמגדירים Flip App, צריך:

• הגדרת שרת OAuth 2.0. מידע נוסף על הגדרה של שרת OAuth זמין במאמר הטמעה של שרת OAuth 2.0.
• יצירת פעולה כדי ליצור פעולה, פועלים לפי ההוראות במאמר יצירת פרויקט של פעולות.

הגדרת 'היפוך אפליקציות' במסוף הפעולות

בקטע הבא מוסבר איך להגדיר היפוך אפליקציות במסוף הפעולות.

1. ממלאים את כל השדות בקטע פרטי לקוח OAuth. (אם אין תמיכה ב-App Flip, ייעשה שימוש ב-OAuth רגיל כחלופה).
2. בקטע שימוש באפליקציה לקישור חשבונות (אופציונלי), מסמנים את האפשרות הפעלה ל-Android.
3. ממלאים את השדות הבאים:
• מזהה אפליקציה: מזהה האפליקציה הוא מזהה ייחודי שהגדרת לאפליקציה.
• חתימת האפליקציה. כדי להתקין אפליקציות ל-Android, צריך להשתמש בהן עם אישור של מפתח ציבורי. למידע על קבלת החתימה של האפליקציה, יש לעיין במאמר אימות הלקוח.
• כוונת ההרשאה. בשדה הזה, מזינים מחרוזת שמציינת את פעולת הכוונה.
4. אם רוצים להגדיר את הלקוח, מוסיפים היקפים ולוחצים על הוספת היקף בקטע הגדרת הלקוח (אופציונלי).
5. לוחצים על שמירה.

הטמעה של אפליקציות חלופיות באפליקציות ל-Android

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

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

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

כדאי לנסות את הדוגמה

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

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

איך זה עובד

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

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

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

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

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

   private fun verifyFingerprint(
           expectedPackage: String,
           expectedFingerprint: String,
           algorithm: String
   ): Boolean {
   
       callingActivity?.packageName?.let {
           if (expectedPackage == it) {
               val packageInfo =
                   packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
               val signatures = packageInfo.signatures
               val input = ByteArrayInputStream(signatures[0].toByteArray())
   
               val certificateFactory = CertificateFactory.getInstance("X509")
               val certificate =
                   certificateFactory.generateCertificate(input) as X509Certificate
               val md = MessageDigest.getInstance(algorithm)
               val publicKey = md.digest(certificate.encoded)
               val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }
   
               return (expectedFingerprint == fingerprint)
           }
       }
       return false
   }
   

3. יש לחלץ את מזהה הלקוח מהפרמטרים של כוונת הרכישה ולוודא שמזהה הלקוח תואם לערך הצפוי.

   private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
   private const val EXPECTED_PACKAGE = "<google-app-package-name>"
   private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
   private const val ALGORITHM = "SHA-256"
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {
   
           // ...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()
   

התוכן של כוונת ההשקה

השדות הבאים ב-Android שמטרתם להפעיל את האפליקציה הם:

• CLIENT_ID (String): 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 כדי לוודא שהחלופה המתאימה הופעלה.

בדיקה של היפוך אפליקציות במכשיר

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

כדי לבדוק את התכונה 'היפוך אפליקציה' דרך אפליקציית Assistant:

1. עוברים אל מסוף הפעולות ובוחרים את הפרויקט שלכם.
2. לוחצים על בדיקה בתפריט הניווט העליון.
3. מפעילים את תהליך קישור החשבונות דרך אפליקציית Assistant:
1. פותחים את אפליקציית Google Assistant.
2. לוחצים על הגדרות.
3. בכרטיסייה של Assistant, לוחצים על בית חכם.
4. לוחצים על הוספה(+).
5. בוחרים את הפעולה מרשימת הספקים. כשלפניו תופיע התחילית '[test]'. כשבוחרים את הפעולה [test] ברשימה, היא אמורה לפתוח את האפליקציה.
6. מוודאים שהאפליקציה הושקה ומתחילים לבדוק את תהליך ההרשאה.

כדי לבדוק לגבי התכונה 'היפוך אפליקציה' מאפליקציית Home:

1. עוברים אל מסוף הפעולות ובוחרים את הפרויקט שלכם.
2. לוחצים על בדיקה בתפריט הניווט העליון.
3. מפעילים את תהליך קישור החשבונות מאפליקציית Home:
1. פותחים את אפליקציית Google Home.
2. לוחצים על לחצן +.
3. לוחצים על הגדרת מכשיר.
4. לוחצים על משהו כבר מוגדר?
5. מרשימת הספקים בוחרים את הפעולה הרצויה בבית החכם. כשלפניו תופיע התחילית '[test]'. כשבוחרים את הפעולה [test] ברשימה, היא אמורה לפתוח את האפליקציה.
6. מוודאים שהאפליקציה הושקה ומתחילים לבדוק את תהליך ההרשאה.