«هم‌پیوندی برنامه» برای iOS

وقتی پیاده‌سازی OAuth 2.0 را انجام دادید، می‌توانید به‌طور اختیاری App Flip مبتنی بر OAuth را پیکربندی کنید که به کاربران iOS شما امکان می‌دهد حساب‌هایشان را در سیستم اصالت‌سنجی شما سریع‌تر به «حساب‌های Google» خود پیوند دهند. بخش‌های زیر نحوه طراحی و پیاده‌سازی App Flip را برای ادغام Cloud-to-cloud در iOS شرح می‌دهند.

دستورالعمل‌های طراحی

این بخش الزامات و توصیه‌های طراحی برای صفحه رضایت اتصال حساب App Flip را شرح می‌دهد. پس از اینکه گوگل برنامه شما را فراخوانی کرد، برنامه شما صفحه رضایت را به کاربر نمایش می‌دهد.

الزامات

  1. شما باید یک بیانیه مجوز گوگل مانند «پس از اتصال، گوگل اجازه کنترل دستگاه‌های شما را خواهد داشت» داشته باشید.
  2. شما باید اطلاع دهید که حساب کاربر به گوگل متصل می‌شود، نه به یک محصول خاص گوگل، مانند گوگل هوم یا دستیار گوگل.
  3. شما باید یک فراخوان عمل واضح در صفحه رضایت خود بیان کنید و از عبارت «موافقم و پیوند» برای اقدام پیوند استفاده کنید. دلیل این امر این است که کاربران باید بدانند برای پیوند دادن حساب‌هایشان، چه داده‌هایی را باید با گوگل به اشتراک بگذارند.
  4. شما باید راهی برای کاربران فراهم کنید تا در صورت عدم تمایل به پیوند، بتوانند به عقب برگردند، آن را رد کنند یا لغو کنند. برای لغو پیوند از عبارت «لغو» استفاده کنید.
  5. شما باید این گردش کار را پیاده‌سازی کنید: پس از کلیک روی «موافقت و پیوند»، باید موفقیت پیوند را نشان دهید و کاربر را به طور خودکار به برنامه Google Home هدایت کنید. اکنون کاربر باید دستگاه پیوند شده را با اقدام شما در برنامه Google Home ببیند. پس از کلیک روی «لغو»، باید کاربر را به برنامه Google Home هدایت کنید.

توصیه‌ها

توصیه می‌کنیم موارد زیر را انجام دهید:

  1. سیاست حفظ حریم خصوصی گوگل را نمایش دهید. پیوندی به سیاست حفظ حریم خصوصی گوگل را در صفحه رضایت‌نامه قرار دهید.

  2. داده‌هایی که باید به اشتراک گذاشته شوند. با زبانی واضح و مختصر به کاربر بگویید که گوگل به چه داده‌هایی از او نیاز دارد و چرا.

  3. امکان لغو پیوند. مکانیزمی برای لغو پیوند کاربران ارائه دهید، مانند URL به تنظیمات حساب کاربری آنها در پلتفرم شما. از طرف دیگر، می‌توانید پیوندی به حساب گوگل قرار دهید که کاربران بتوانند حساب پیوند شده خود را مدیریت کنند.

  4. امکان تغییر حساب کاربری. روشی را برای کاربران پیشنهاد دهید تا حساب(های) خود را تغییر دهند. این امر به ویژه در صورتی مفید است که کاربران تمایل به داشتن چندین حساب داشته باشند.

    • اگر کاربری برای تغییر حساب کاربری باید صفحه رضایت را ببندد، یک خطای قابل بازیابی به گوگل ارسال کنید تا کاربر بتواند با پیوند OAuth و جریان ضمنی به حساب مورد نظر خود وارد شود.

  5. لوگوی خود را قرار دهید. لوگوی شرکت خود را در صفحه رضایت‌نامه نمایش دهید. از دستورالعمل‌های سبک خود برای قرار دادن لوگوی خود استفاده کنید. اگر می‌خواهید لوگوی گوگل را نیز نمایش دهید، به بخش لوگوها و علائم تجاری مراجعه کنید.

این شکل یک نمونه صفحه رضایت‌نامه را به همراه الزامات فردی و توصیه‌هایی که باید هنگام طراحی صفحه رضایت‌نامه کاربر رعایت شوند، نشان می‌دهد.
شکل ۱: دستورالعمل‌های طراحی صفحه رضایت‌نامه اتصال حساب کاربری.

راه‌اندازی برای App Flip مبتنی بر OAuth

بخش‌های زیر پیش‌نیازهای «هم‌پیوندی برنامه» مبتنی بر OAuth و نحوه پیکربندی پروژه «هم‌پیوندی برنامه» را در «کنسول توسعه‌دهنده Google Home» شرح می‌دهد.

یکپارچه‌سازی «ابر به ابر» ایجاد کنید و سرور OAuth 2.0 راه‌اندازی کنید

قبل‌از اینکه بتوانید App Flip را پیکربندی کنید، باید کارهای زیر را انجام دهید:

پیکربندی «هم‌پیوندی برنامه» در «کنسول توسعه‌دهنده»

بخش زیر نحوه پیکربندی «هم‌پیوندی برنامه» را در کنسول توسعه‌دهنده شرح می‌دهد.

  1. همه فیلدهای زیر اطلاعات کارخواه OAuth را تکمیل کنید. (اگر از App Flip پشتیبانی نشود، از OAuth معمولی به‌عنوان جایگزین استفاده می‌شود.)
  2. در بخش استفاده از برنامه برای پیوند دادن حساب(اختیاری)، فعال کردن برای iOS را علامت بزنید.
  3. فیلد پیوند جامع را تکمیل کنید. برای اطلاعات بیشتر درباره پیوندهای جامع، به اجازه دادن به برنامه‌ها و وب‌سایت‌ها برای پیوند دادن به محتوای شما مراجعه کنید.
  4. اگر می‌خواهید به‌طور اختیاری مشتری‌تان را پیکربندی کنید، دامنه‌ها را اضافه کنید و روی افزودن دامنه در بخش پیکربندی مشتری (اختیاری) کلیک کنید.
  5. روی ذخیره کلیک کنید.

اکنون می‌توانید به بخش بعدی بروید تا App Flip را در برنامه iOS خود پیاده‌سازی کنید.

App Flip را در برنامه‌های بومی‌تان پیاده‌سازی کنید

برای پیاده‌سازی App Flip، باید کد مجوز کاربر را در برنامه‌تان اصلاح کنید تا پیوند عمیق از Google را بپذیرد.

پیوند دادن App Flip مبتنی بر OAuth‏ (App Flip) برنامه iOS شما را از برنامه Google باز می‌کند تا به کاربر برنامه Google کمک کند حسابش را راحت‌تر پیوند دهد. برای پیاده‌سازی این ویژگی، باید تغییرات جزئی در کد برنامه iOS خود ایجاد کنید.

در این سند، با نحوه اصلاح برنامه iOS برای پشتیبانی از «هم‌پیوندی برنامه» آشنا می‌شوید.

امتحان کردن نمونه

برنامه نمونه «هم‌پیوندی برنامه» ادغام پیونددهی حساب را در iOS که با «هم‌پیوندی برنامه» سازگار است نشان می‌دهد. می‌توانید از این برنامه برای درستی‌سنجی نحوه پاسخ دادن به پیوند جامع «هم‌پیوندی برنامه» ورودی از برنامه‌های تلفن همراه Google استفاده کنید.

برنامه نمونه ازپیش پیکربندی شده است تا با ابزار آزمایش App Flip برای iOS ادغام شود، که می‌توانید از آن برای تأیید ادغام برنامه iOS خود با App Flip قبل‌از پیکربندی پیوند حساب با Google استفاده کنید. این برنامه پیوند جامع را شبیه‌سازی می‌کند که وقتی «هم‌پیوندی برنامه» فعال باشد، توسط برنامه‌های تلفن همراه Google راه‌اندازی می‌شود.

روش کار

مراحل جریان زیر مراحلی است که برنامه Google و برنامه شما هنگام رخ دادن «هم‌پیوندی برنامه» طی می‌کنند:

  1. برنامه Google تلاش می‌کند پیوند جامع برنامه‌تان را باز کند. اگر برنامه در دستگاه کاربر نصب شده باشد و با پیوند جامع مرتبط باشد، می‌تواند آن را باز کند. برای جزئیات، پشتیبانی از پیوندهای جامع را ببینید.

  2. برنامه شما بررسی می‌کند که پارامتر client_id و redirect_uri کدگذاری‌شده در نشانی وب ورودی با پیوند جامع Google موردانتظار مطابقت داشته باشد.

  3. برنامه شما کد مجوزی را از سرور OAuth2 شما درخواست می‌کند. در پایان این جریان، برنامه شما یا کد مجوز یا خطایی را به برنامه Google برمی‌گرداند. برای انجام این کار، پیوند جامع Google را با پارامترهای پیوست‌شده برای کد مجوز یا خطا باز می‌کند.

  4. برنامه Google پیوند جامع Google ورودی را مدیریت می‌کند و با بقیه جریان ادامه می‌دهد. اگر کد مجوز ارائه شود، پیوند دادن فوراً تکمیل می‌شود. تبادل کد به‌صورت سروربه‌سرور انجام می‌شود، درست مثل جریان پیونددهی OAuth مبتنی بر مرورگر. اگر کد خطا برگردانده شود، جریان پیوند دادن با گزینه‌های جایگزین ادامه می‌یابد.

برنامه iOS خود را برای پشتیبانی از «هم‌پیوندی برنامه» اصلاح کنید

برای پشتیبانی از «هم‌پیوندی برنامه»، تغییرات کد زیر را در برنامه iOS خود اعمال کنید:

  1. NSUserActivityTypeBrowsingWeb را در App Delegate خود مدیریت کنید.
  2. پارامترهای redirect_uri و state را از نشانی وب ضبط کنید تا بعداً استفاده کنید.
  3. بررسی کنید redirect_uri با این قالب مطابقت داشته باشد: 
    https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

  4. بررسی کنید که شناسه مشتری با مقدار موردانتظار مطابقت داشته باشد. از نمونه کد زیر استفاده کنید:

    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
    }
}

  5. پس‌از صدور موفقیت‌آمیز مجوز، 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)
    }
}

  6. اگر خطایی رخ داد، به‌جای آن نتیجه خطا را به شناسه منبع یکسان تغییرمسیر پیوست کنید. از نمونه کد زیر استفاده کنید:

    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 «flip» برای باز کردن برنامه Google و ارسال نتایج.

پارامترهای مورداستفاده هنگام برگرداندن موفقیت‌آمیز نتیجه مجوز:

  • code (String): مقدار کد مجوز، درصورت دردسترس بودن.
  • ‫state (String): مقدار دقیقی که از پیوند جامع ورودی دریافت شده است.

پارامترهای مورداستفاده درصورت ناموفق بودن نتیجه مجوز:

  • error (String)، با مقادیر زیر:

    • ‫cancelled: خطای قابل‌بازیابی. برنامه Google تلاش می‌کند بااستفاده از نشانی وب مجوز، حساب را پیوند دهد. برخی‌از نمونه‌ها عبارت‌اند از: عدم موفقیت کاربر در ورود به سیستم، آفلاین بودن دستگاه، یا اتمام مهلت اتصال.
    • unrecoverable: خطای غیرقابل‌بازیابی. برای مثال، کاربر تلاش می‌کند با حساب غیرفعال‌شده‌ای پیوند برقرار کند.برنامه Google پیوند دادن حساب را لغو می‌کند.
    • invalid_request: پارامترهای درخواست نامعتبر است یا وجود ندارد. این خطای بازیاب‌پذیر است. برنامه Google تلاش می‌کند بااستفاده از نشانی وب مجوز، حساب را پیوند دهد.
    • access_denied: کاربر درخواست رضایت را رد می‌کند. این خطا غیرقابل‌بازیابی است؛ برنامه Google پیوند دادن را لغو می‌کند.

  • ‫error_description (String، اختیاری): پیام خطای کاربرپسند.

برای همه انواع خطا، باید داده‌های پاسخ را به REDIRECT_URI مشخص‌شده برگردانید تا مطمئن شوید که جایگزین مناسب فعال می‌شود.

نقطه پایانی مجوزتان را برای پشتیبانی از «هم‌پیوندی برنامه» اصلاح کنید

پلاتفرم خود را برای پذیرش درخواست‌ها بااستفاده از نشانی‌های وب هدایت هم‌پیوندی برنامه 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» 
    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)، پیوند دادن حساب «خانه هوشمند» از نشانی‌های وب هدایتگر com.google.Chromecast استفاده می‌کند. مطمئن شوید سرور مجوزدهی شما این نشانی‌های وب هدایتگر را مجاز می‌کند.

بررسی کنید که client_id و نشانی وب مشخص‌شده با پارامتر redirect_uri با مقادیر موردانتظار هنگام دریافت درخواست مطابقت داشته باشند. اگر درستی‌سنجی کارخواه ناموفق بود، خطای invalid_request را به redirect_uri برگردانید.

App Flip را در دستگاهتان آزمایش کنید

اکنون که ادغام «ابر به ابر» را ایجاد کرده‌اید و «هم‌پیوندی برنامه» را در کنسول و در برنامه‌تان پیکربندی کرده‌اید، می‌توانید «هم‌پیوندی برنامه» را در دستگاه همراهتان آزمایش کنید. می‌توانید از برنامه Google Home برای آزمایش «هم‌پیوندی برنامه» استفاده کنید.

برای آزمایش App Flip از برنامه Google Home، این مراحل را دنبال کنید:

  1. به کنسول توسعه‌دهنده بروید و پروژه خود را انتخاب کنید.
  2. به Cloud-to-cloud > آزمایش بروید.
  3. جریان پیوند دادن حساب را از برنامه Home راه‌اندازی کنید:
    1. Google Home app (GHA) را باز کنید.
    2. روی دکمه + کلیک کنید.
    3. روی راه‌اندازی دستگاه کلیک کنید.
    4. روی قبلاً چیزی راه‌اندازی کرده‌اید؟ کلیک کنید.
    5. ادغام «ابر به ابر» خود را از فهرست ارائه‌دهندگان انتخاب کنید. در فهرست، پیشوند «[test]» به آن اضافه خواهد شد. وقتی ادغام [آزمایشی] خود را از فهرست انتخاب می‌کنید، باید برنامه‌تان را باز کند.
    6. بررسی کنید که برنامه‌تان راه‌اندازی شده باشد و آزمایش جریان مجوزدهی را شروع کنید.
قبلی
Android
بعدی
شناسایی و همگام‌سازی