‫Google מעבירה את הטיפול בקישור חשבונות של צד שלישי לבית חכם לטיפול מלא ועצמאי באפליקציית Google Home. יכול להיות שיהיה צורך לבצע עדכונים בשילוב לפני 30 באוקטובר 2026. מידע נוסף זמין במדריך להעברת נתונים של קישור חשבונות.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

אפליקציית Flip ל-iOS

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

הנחיות עיצוב

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

דרישות

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

המלצות

מה אתם יכולים לעשות?

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

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

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

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

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

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

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

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

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

ממלאים את כל השדות בקטע OAuth Client information (פרטי לקוח OAuth). (אם אין תמיכה ב-App Flip, המערכת תשתמש ב-OAuth רגיל כגיבוי).
בקטע Use your app for account linking(optional), מסמנים את האפשרות Enable for iOS.
ממלאים את השדה קישור אוניברסלי. מידע נוסף על קישורים אוניברסליים זמין במאמר איך מאפשרים לאפליקציות ולאתרים לקשר לתוכן שלכם.
אם רוצים להגדיר את הלקוח, מוסיפים היקפים ולוחצים על Add scope בקטע Configure your client (optional).
לוחצים על שמירה.

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

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

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

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

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

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

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

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

איך זה עובד

אלה השלבים בתהליך שמתרחש באפליקציית Google ובאפליקציה שלכם כשמתבצע קישור אפליקציות:

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

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

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

מטפלים ב-NSUserActivityTypeBrowsingWeb ב-App Delegate.
מתעדים את הפרמטרים redirect_uri ו-state מכתובת ה-URL כדי להשתמש בהם בהמשך.

צריך לוודא שהערך של redirect_uri תואם לפורמט הזה:

https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

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

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([Any]?) -> Void) -> Bool
{
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL,
        let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),
        let params = components.queryItems else {
            return false
    }

    if let clientId = params.filter({$0.name == "client_id"}).first?.value,
        let state = params.filter({$0.name == "state"}).first?.value,
        let redirectUri = params.filter({$0.name == "redirect_uri"}).first?.value {

        // Save the redirect_uri and state for later...

        // Verify the client id
        return (clientId == GOOGLE_CLIENT_ID)
    } else {
        // Missing required parameters
        return false
    }
}

אחרי שההרשאה תאושר, צריך לקרוא ל-URI של ההפניה האוטומטית עם קוד ההרשאה. משתמשים בדוגמת הקוד הבאה:

func returnAuthCode(code: String, state: String, redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramAuthCode = URLQueryItem(name: "code", value: code)
    let paramState = URLQueryItem(name: "state", value: state)
    components?.queryItems = [paramAuthCode, paramState]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

אם אירעה שגיאה, צריך לצרף תוצאת שגיאה ל-URI להפניה אוטומטית. משתמשים בדוגמת הקוד הבאה:

func returnError(redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramError = URLQueryItem(name: "error", value: "invalid_request")
    let paramDescription = URLQueryItem(name: "error_description", value: "Invalid Request")
    components?.queryItems = [paramError, paramDescription]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

פרמטרים של שאילתה לקישור האוניברסלי של האפליקציה

כשאפליקציית Google פותחת את הקישור האוניברסלי של האפליקציה, הוא כולל את הפרמטרים הבאים של השאילתה:

‫client_id (String): client_id של Google שרשום באפליקציה.
‫scope (List of String): רשימה של היקפי הרשאות מבוקשים, מופרדים ברווחים.
state ‏ (String): מספר חד-פעמי שמשמש את Google כדי לוודא שתוצאת ההרשאה היא בתגובה לבקשה היוצאת של Google.
‫redirect_uri (String): הקישור האוניברסלי של Google. ה-URI של "ההעברה" לפתיחת אפליקציית Google והעברת התוצאות.

פרמטרים של שאילתה לקישור האוניברסלי של Google

פרמטרים שמשמשים כשתוצאת ההרשאה מוחזרת בהצלחה:

‫code (String): הערך של קוד ההרשאה, אם הוא זמין.
‫state (String): הערך המדויק שהתקבל מהקישור האוניברסלי הנכנס.

פרמטרים שמשמשים כשתוצאת ההרשאה מוחזרת ללא הצלחה:

‫error (String), עם הערכים הבאים:
- ‫cancelled: שגיאה שניתן לתקן. אפליקציית Google תנסה לקשר את החשבון באמצעות כתובת ה-URL להרשאה. לדוגמה, אם המשתמש לא מצליח להיכנס לחשבון, אם המכשיר במצב אופליין או אם הזמן הקצוב לתפוגה של החיבור חלף.
- ‫unrecoverable: שגיאה שבעקבותיה אי אפשר לשחזר. לדוגמה, המשתמש מנסה לקשר חשבון מושבת.אפליקציית Google תבטל את קישור החשבון.
- ‫invalid_request: הפרמטרים של הבקשה לא תקינים או חסרים. זו שגיאה שאפשר לתקן. אפליקציית Google תנסה לקשר את החשבון באמצעות כתובת ה-URL להרשאה.
- ‫access_denied: המשתמש דוחה את בקשת ההסכמה. זו שגיאה שלא ניתן לתקן, ואפליקציית Google מבטלת את הקישור.
‫error_description (String, אופציונלי): הודעת שגיאה ידידותית למשתמש.

הערה: למידע נוסף על שגיאות אפשריות ועל התוכן האופציונלי של השדה error_description, קראו את תקן OAuth 2.0.

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

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

מגדירים את הפלטפורמה כך שתקבל בקשות באמצעות כתובות ה-URL להפניה אוטומטית של Google לקישור אפליקציות:

אפליקציית Google Home

https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast

אפליקציית Google Assistant

https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.OPA
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA

ב-Google Home app (GHA), קישור החשבון לבית החכם משתמש בכתובות ה-URL להפניה אוטומטית של com.google.Chromecast. ודאו ששרת ההרשאות שלכם מאפשר את כתובות ה-URL האלה להפניה אוטומטית.

צריך לוודא שהערך של client_id וכתובת ה-URL שצוינה בפרמטר redirect_uri תואמים לערכים הצפויים כשמתקבלת בקשה. אם אימות הלקוח נכשל, מחזירים את השגיאה invalid_request אל redirect_uri.

בדיקת App Flip במכשיר

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

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

נכנסים אל Developer Console ובוחרים את הפרויקט.
עוברים אל Cloud-to-cloud > Test.
מפעילים את תהליך קישור החשבון מאפליקציית Home:

פותחים את Google Home app (GHA).
לוחצים על הכפתור +.
לוחצים על הגדרת המכשיר.
לוחצים על כבר הגדרת משהו?
בוחרים את השילוב בין שירותי הענן מרשימת הספקים. הוא יופיע ברשימה עם הקידומת "[test]". כשבוחרים את השילוב [למטרות בדיקה] מהרשימה, האפליקציה אמורה להיפתח.
מוודאים שהאפליקציה הופעלה ומתחילים לבדוק את תהליך ההרשאה.

Android

זיהוי וסנכרון