يمكنك بدء عملية ربط حساب Google مباشرةً من منصتك.

Account Linking can be completed directly within your mobile app, allowing your users to link their account on your service with their Google Account. The established link grants Google access to the data the user consents to share.

يحسّن هذا الأسلوب أداء ربط الحسابات من خلال جذب المستخدمين ضمن السياق المألوف لتطبيقك بدلاً من محادثة مع "مساعد Google". ويمكن دمجه في عملية إعداد المستخدمين والإعدادات ومساحات عرض التطبيقات الأخرى، ما يتيح فرصًا لاكتشاف "إجراء Google Assistant" والتفاعل معه. على سبيل المثال، بعد ربط الحساب، يمكنك أن تعرض على المستخدم الانتقال مباشرةً إلى "الإجراء".

تتضمَّن مزايا المستخدمين ما يلي:

  • يمكن للمستخدمين بدء عملية ربط الحساب في تطبيقك وإكمالها، وهي بيئة يعرفونها جيدًا.
  • لا يطلب المستخدمون بيانات اعتماد تسجيل الدخول لأنه تمت مصادقتها من قبل على الجهاز وفي تطبيقك المتوافق مع الأجهزة الجوَّالة.

تتضمن مزايا مطوّري البرامج ما يلي:

  • يمكنك التحكُّم في المكان الذي يتم فيه الترويج لربط الحساب في تطبيقك المتوافق مع الأجهزة الجوّالة وبدئه، على سبيل المثال، في إعدادات المستخدم أو على الإعلانات البينية أو بعد تسجيل دخول المستخدم إلى تطبيقك المتوافق مع الأجهزة الجوّالة. وتؤدي إضافة نقاط إدخال متعددة لبدء ربط الحساب إلى تسهيل اكتشاف الحساب. ، ما يؤدي إلى زيادة التفاعل وعدد الحسابات المرتبطة.
  • في معدّل الإحالات الناجحة عندما يتمكّن المستخدمون من إكمال عملية الربط بعدد خطوات أقل من خطوات OAuth العادية المستندة إلى الويب.
  • يتطلّب تنفيذ الرابط من نظامك الأساسي (Android) جهدًا هندسيًا منخفضًا لأن هذه العملية تستفيد من تنفيذ OAuth2.0 الحالي، بافتراض أنك نفّذت واحدًا بالفعل.
  • معدلات الانقطاع المخفَّضة نظرًا لعدم حاجة المستخدمين إلى إعادة إدخال بيانات اعتماد تسجيل الدخول والتمكن من إكمال العملية بخطوات أقل. يمكن أن تصل معدلات الانسحاب إلى 80% في التدفقات التي يُطلب فيها من المستخدمين إدخال بيانات اعتماد تسجيل الدخول وإدخالها.

آلية العمل

يتم إكمال عملية الربط من منصتك باتّباع الخطوات التالية:

  1. ينقر المستخدم على مشغّل الربط أو يفعّله في تطبيقك على الأجهزة الجوّالة.
  2. يختار المستخدم حساب Google المطلوب ربطه.
    1. يختار المستخدم حساب Google حاليًا على الجهاز لربطه، أو يسجِّل الدخول باستخدام حساب جديد.
  3. تظهر للمستخدم شاشات طلب الموافقة التي تستضيفها Google، وعليه الموافقة على المتابعة أو النقر على "إلغاء" لإيقاف عملية الربط مع حساب حالي.
  4. تظهر للمستخدم شاشة طلب الموافقة، وعليه الموافقة على المتابعة أو النقر على "إلغاء" لإيقاف عملية الربط مع حساب حالي.
  5. يتم إنشاء الرابط بين حساب المستخدم على خدمتك وحسابه على Google.

الشكل 1 مخطط عملية الربط من منصتك

المتطلبات

لتنفيذ عملية الربط من منصتك، يجب توفّر ما يلي:

  • تطبيق Android
  • خادم OAuth 2.0 تملكه وتديره وتتولى صيانته، ويتوافق مع مسار رمز تفويض OAuth 2.0

الإعداد

قبل المتابعة إلى الخطوات أدناه، يجب إكمال عملية تسجيل "ربط الحساب" registration process.

إعداد بيئة التطوير

احصل على أحدث إصدار من "خدمات Google Play" على جهاز التطوير المضيف:

  1. افتح مدير حزمة تطوير البرامج (SDK) لنظام التشغيل Android.

  1. ضمن أدوات حزمة تطوير البرامج (SDK)، ابحث عن خدمات Google Play.

  2. إذا لم تكن حالة هاتَين الحزمتَين "مثبّتة"، اختَرهما معًا وانقر على تثبيت الحِزم.

ضبط التطبيق

  1. في ملف build.gradle على مستوى المشروع، أدرِج مستودع Maven من Google في كلٍّ من قسمَي buildscript وallprojects.

    buildscript {
    repositories {
        google()
    }
}

allprojects {
    repositories {
        google()
    }
}

  2. أضِف التبعيات لواجهة برمجة التطبيقات "الربط بحساب Google" إلى ملف Gradle على مستوى التطبيق في الوحدة، والذي يكون عادةً app/build.gradle:

    dependencies {
  implementation 'com.google.android.gms:play-services-auth:21.6.0'
}

ستؤدي عملية الربط من منصتك إلى حفظ Google لرمز وصول توفّره خدمتك. يجب الحصول على الموافقة قبل عرض الرمز للمستخدم.

اتّبِع الخطوات التالية للحصول على موافقة المستخدم وعرض رمز تفويض من خلال حزمة تطوير البرامج (SDK) لخدمات Google Play.

  1. أنشئ كائن PendingIntent يمكنه تشغيل نشاط طلب الموافقة. يتم تشغيل الموافقة من خلال واجهة برمجة التطبيقات Play Services API. عليك تقديم PendingIntent (يُشار إليه باسم consentPendingIntent لتوضيح المعنى) عند استدعاء واجهة برمجة التطبيقات.

    Kotlin

    // Build a PendingIntent that can launch the consent activity
val consentPendingIntent = buildConsentPendingIntent()

    جافا

    // Build a PendingIntent that can launch your consent activity
PendingIntent consentPendingIntent =
          buildConsentPendingIntent();

  2. أنشئ النشاط المقابل للتعامل مع هدف طلب الموافقة.

    Kotlin

      class ConsentActivity : AppCompatActivity

  private fun onConsentAccepted() {
      // Obtain a token (for simplicity, we’ll ignore the async nature
      // of the following call)
      val token = getToken()
      val intent = Intent()
                  .putExtra(SaveAccountLinkingTokenRequest.EXTRA_TOKEN,
                            token)
      setResult(Activity.RESULT_OK, intent)
      finish()
  }

  private fun onConsentRejectedOrCanceled() {
      setResult(Activity.RESULT_CANCELED)
      finish()
  }

    جافا

      public class ConsentActivity extends AppCompatActivity {
    ...
    private void onConsentAccepted() {
      // Obtain a token (for simplicity, we’ll ignore the async nature of
      // the following call
      String token = getToken();
      Intent intent = new Intent();
      intent.putExtra(SaveAccountLinkingTokenRequest.EXTRA_TOKEN, token);
      setResult(Activity.RESULT_OK, intent);
      finish();
    }

    private void onConsentRejectedOrCanceled() {
      setResult(Activity.RESULT_CANCELED, null);
      finish();
    }
 }

    نحن نفترض أنّه يتم استدعاء الطريقتَين onConsentAccpeted() وonConsentRejectedOrCanceled() إذا وافق المستخدم على طلب الموافقة أو رفضه أو ألغاه، على التوالي.

  3. أنشئ طلبًا لحفظ الرمز، وضِمن مَعلمات الإعداد الأخرى، مرِّر PendingIntent الذي تم إنشاؤه في الخطوة 1 أعلاه.

    Kotlin

      // Create an ActivityResultLauncher which registers a callback for the
  // Activity result contract
  val activityResultLauncher = registerForActivityResult(
    ActivityResultContracts.StartIntentSenderForResult())
    { result ->
      if (result.resultCode == RESULT_OK) {
        // Successfully finished the flow and saved the token
      } else {
        // Flow failed, for example the user may have canceled the flow
      }
    }

  // Build token save request
  val request = SaveAccountLinkingTokenRequest.builder()
    .setTokenType(SaveAccountLinkingTokenRequest.TOKEN_TYPE_AUTH_CODE)
    .setConsentPendingIntent(consentPendingIntent)
    .setServiceId("service-id-of-and-defined-by-developer")
    //Set the scopes that the token is valid for on your platform
    .setScopes(scopes)
    .build()

   // Launch consent activity and retrieve token
   Identity.getCredentialSavingClient(this)
     .saveAccountLinkingToken(request)
     .addOnSuccessListener( saveAccountLinkingTokenResult -> {
        if (saveAccountLinkingTokenResult.hasResolution()) {
          val pendingIntent = saveAccountLinkingTokenResult
                              .getPendingIntent()
          val intentSenderRequest = IntentSenderRequest
                                    .Builder(pendingIntent).build()
          activityResultLauncher.launch(intentSenderRequest)
        } else {
           // This should not happen, let’s log this
           Log.e(TAG, "Failed to save token");
        }
      })
      .addOnFailureListener(e -> Log.e(TAG, “Failed to save token”, e))

    جافا

      // Create an ActivityResultLauncher which registers a callback for the
  // Activity result contract
  ActivityResultLauncher<IntentSenderRequest>
      activityResultLauncher =
      registerForActivityResult(new ActivityResultContracts
                                    .StartIntentSenderForResult(),
                                result -> {
      if (result.getResultCode() == RESULT_OK) {
          // Successfully finished the flow and saved the token
      } else {
          // Flow failed, for example the user may have canceled the flow
      }
  });

 // Build token save request
 SaveAccountLinkingTokenRequest request =
    SaveAccountLinkingTokenRequest.builder()
        .setTokenType(
            SaveAccountLinkingTokenRequest.TOKEN_TYPE_AUTH_CODE)
        .setConsentPendingIntent(consentPendingIntent)
        .setServiceId("service-id-of-and-defined-by-developer")
        //Set the scopes that the token is valid for on your platform
        .setScopes(scopes)
        .build();

  // Launch consent activity and retrieve token
  Identity.getCredentialSavingClient(this)
      .saveAccountLinkingToken(request)
      .addOnSuccessListener(
          saveAccountLinkingTokenResult -> {
            if (saveAccountLinkingTokenResult.hasResolution()) {
              // Launch the resolution intent
              PendingIntent pendingIntent =
                  saveAccountLinkingTokenResult.getPendingIntent();
              IntentSenderRequest intentSenderRequest =
                  new IntentSenderRequest.Builder(pendingIntent).build();
              activityResultLauncher.launch(intentSenderRequest);
            } else {
              // This should not happen, let’s log this
              Log.e(TAG, "Failed to save token");
            }
          })
      .addOnFailureListener(e -> Log.e(TAG, "Failed to save token", e));
  ```

تطلب الخطوات أعلاه من المستخدم الموافقة وتعرض رمز تفويض على Google.

أفضل الممارسات

  • يجب أن يشير تطبيقك إلى حالة الربط للمستخدم من خلال زر أو مفتاح تبديل أو عنصر مرئي مشابه.

    الشكل 1 صورة نموذجية لحالة الربط

  • عليك إعلام المستخدم بعد إتمام عملية الربط بنجاح، مثلاً عرض إشعار مؤقت أو تغيير حالة مفتاح تبديل أو إعادة توجيه المستخدم إلى صفحة منفصلة تشير إلى نجاح عملية الربط.

  • عليك التفكير في مطالبة المستخدمين داخل التطبيق بربط الحسابات، ويُفضَّل أن يكون ذلك استنادًا إلى إشارات قوية تشير إلى أنّ الربط سيفيد هؤلاء المستخدمين.

  • بعد إتمام عملية الربط بنجاح، عليك تزويد المستخدمين بمثال على ما يمكنهم فعله باستخدام الحساب المرتبط، مثلاً إذا تم ربط خدمة بثّ موسيقى، اطلب من "مساعد Google" تشغيل موسيقى.

  • امنح المستخدمين إمكانية إدارة حساباتهم المرتبطة، بما في ذلك خيار إلغاء ربطها. وجِّههم إلى صفحة إدارة الحسابات المرتبطة على Google، أي https://myaccount.google.com/accountlinking.

مراجع

مستندات مرجع واجهة برمجة التطبيقات Android auth API