تسجيل الدخول إلى ألعاب Android

للوصول إلى وظائف "خدمات ألعاب Google Play"، يجب أن توفر لعبتك حساب المشغّل الذي تم تسجيل الدخول إليه. يوضّح هذا المستند كيفية تنفيذ تجربة تسجيل دخول سلسة في لعبتك.

توفّر حزمة تطوير البرامج (SDK) للإصدار 2 من "خدمات ألعاب Play" عددًا من التحسينات التي تزيد من عدد المستخدمين الذين سجّلوا الدخول إلى لعبتك، وتُسهل عملية التطوير:

  • تحسينات للمستخدمين:
    • بعد اختيار حساب تلقائي، يتم تسجيل دخول المستخدمين بدون الحاجة إلى التفاعل من خلال رسالة مطالبة.
    • لم يعد المستخدمون بحاجة إلى تنزيل تطبيق "ألعاب Play" لتسجيل الدخول باستخدام "خدمات ألعاب Play" أو إنشاء حساب جديد.
    • يمكن للمستخدمين الآن إدارة حساباتهم على "خدمات ألعاب Play" للألعاب المتعددة من صفحة واحدة.
  • تحسينات للمطوّرين:
    • لم يعُد رمز العميل بحاجة إلى معالجة عملية تسجيل الدخول أو تسجيل الخروج، إذ يتم تشغيل تسجيل الدخول تلقائيًا عند بدء اللعبة، وتتم معالجة إدارة الحساب في إعدادات نظام التشغيل.

دمج عميل جديد

يوضّح هذا القسم كيفية تنفيذ عملية دمج جديدة لبرنامج باستخدام "خدمات ألعاب Play" الإصدار 2.

إضافة التبعية

أضِف حزمة تطوير البرامج (SDK) الخاصة بخدمات ألعاب Play إلى ملف build.gradle الخاص بتطبيقك على مستوى الجذر. إذا كنت تستخدم Gradle، يمكنك إضافة التبعية أو تعديلها على النحو التالي:

dependencies {
 implementation "com.google.android.gms:play-services-games-v2:+"
}

تحديد معرّف المشروع

لإضافة رقم تعريف مشروع SDK لخدمات ألعاب Play إلى تطبيقك، يُرجى إكمال الخطوات التالية:

  1. في ملف AndroidManifest.xml بتطبيقك، أضِف عنصر <meta-data> والسمات التالية إلى عنصر <application>:

    <manifest>
  <application>
    <meta-data android:name="com.google.android.gms.games.APP_ID"
               android:value="@string/game_services_project_id"/>
  </application>
</manifest>

    حدِّد مرجع مورد السلسلة @string/game_services_project_id باستخدام رقم تعريف مشروع خدمات الألعاب في ألعابك على أنّه القيمة. ويمكن العثور على رقم تعريف مشروع خدمات الألعاب أسفل اسم اللعبة في صفحة التهيئة على Google Play Console.

  2. في ملف res/values/strings.xml، أضف مرجعًا لمورد السلسلة وعيِّن رقم تعريف مشروعك كقيمة. في Google Play Console، يمكنك العثور على رقم تعريف المشروع أسفل اسم اللعبة في صفحة الإعداد. مثلاً:

    <!-- res/values/strings.xml -->
<resources>
  <!-- Replace 0000000000 with your game’s project id. Example value shown above.  -->
  <string translatable="false"  name="game_services_project_id"> 0000000000 </string>
</resources>

إعداد حزمة تطوير البرامج (SDK)

يجب إعداد حزمة تطوير البرامج (SDK) الخاصة بـ "ألعاب Play" عند معاودة الاتصال بـ "onCreate(..)" ضمن فئة Application.

import com.google.android.gms.games.PlayGamesSdk;

...

@Override
public void onCreate(){
  super.onCreate();
  PlayGamesSdk.initialize(this);
}

الحصول على نتيجة تسجيل الدخول

عند تشغيل اللعبة، ستحاول دائمًا تسجيل دخول المستخدم. ولمصادقة المستخدم، يجب التحقق من تسجيل المستخدم الدخول بنجاح، ثم الحصول على "معرّف اللاعب".

للتحقق من محاولة تسجيل الدخول، اتصل بـ GamesSignInClient.isAuthenticated() واستخدم addOnCompleteListener لاسترداد النتائج. مثلاً:

GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(getActivity());

gamesSignInClient.isAuthenticated().addOnCompleteListener(isAuthenticatedTask -> {
  boolean isAuthenticated =
    (isAuthenticatedTask.isSuccessful() &&
     isAuthenticatedTask.getResult().isAuthenticated());

  if (isAuthenticated) {
    // Continue with Play Games Services
  } else {
    // Disable your integration with Play Games Services or show a
    // login button to ask  players to sign-in. Clicking it should
    // call GamesSignInClient.signIn().
  }
});

إذا اختار المستخدم عدم تسجيل الدخول عند تشغيل اللعبة، يمكنك اختيار مواصلة عرض زر يتضمّن رمز "ألعاب Play" ومحاولة تسجيل دخول المستخدم مرة أخرى من خلال الاتصال بـ GamesSignInClient.signIn() في حال ضغط المستخدم على الزر.

بعد التأكّد من أنّ المستخدم قد سجّل دخوله، يمكنك استرداد "معرّف المشغّل" لتحديد هوية المستخدم. مثلاً:

PlayGames.getPlayersClient(activity).getCurrentPlayer().addOnCompleteListener(mTask -> {
    // Get PlayerID with mTask.getResult().getPlayerId()
  }
);
.

نقل البيانات إلى الإصدار 2 من ميزة تسجيل الدخول في "خدمات ألعاب Play"

يوضّح هذا القسم كيفية نقل رمز العميل من الإصدار 1 إلى الإصدار 2 من "خدمات ألعاب Play".

تحتوي حزمة تطوير البرامج (SDK) الجديدة على أربعة تغييرات رئيسية لزيادة نجاح عملية تسجيل الدخول عليك الانتباه إليها:

  1. يتم تشغيل تسجيل الدخول تلقائيًا عند إطلاق لعبتك. بدلاً من استخدام GoogleSignInClient في GoogleSignIn SDK لتسجيل الدخول، يمكنك استخدام GamesSignInClient.isAuthenticated() لجلب نتيجة محاولة تسجيل الدخول التلقائي.
  2. لن تحتاج فئات Client Fi إلى تمرير عنصر GoogleSignInAccount بعد الآن. لا يمكن طلب نطاقات OAuth إضافية (سيتم طلب GAMES_LITE تلقائيًا).
  3. يتم الآن توفير الرموز المميّزة للمصادقة باستخدام "GamesSignInClient.requestServerSideAccess()" ضمن حزمة تطوير البرامج (SDK) لـ "خدمات ألعاب Play".
  4. لقد أزلنا طريقة تسجيل الخروج ولن نحتاج بعد الآن إلى توفّر زرّ داخل اللعبة لتسجيل الدخول إلى "خدمات ألعاب Play" أو تسجيل الخروج منها.

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

استهداف مستودع Maven الجديد لحزمة تطوير البرامج (SDK)

إذا كنت تستخدم نظام إنشاء Gradle، يمكن إجراء ذلك عن طريق تغيير التبعية إلى أداة com.google.android.gms:play-services-games-v2:+ في ملف build.gradle في الوحدة. مثلاً:

dependencies {
 implementation "com.google.android.gms:play-services-games-v2:+"
}

إعداد حزمة تطوير البرامج (SDK)

يجب إعداد حزمة تطوير البرامج (SDK) الخاصة بـ "ألعاب Play" في معاودة الاتصال بالرمز onCreate(..) للصف Application. مثلاً:

import com.google.android.gms.games.PlayGamesSdk;

...

@Override
public void onCreate(){
  super.onCreate();
  PlayGamesSdk.initialize(this);
}

إزالة مكالمات تسجيل الدخول وتسجيل الخروج

وإذا لم تحدد أي نطاقات إضافية، يجب أن تتم عملية نقل حالة الاستخدام بشكل مباشر.

  1. يمكنك إزالة طلبات تسجيل الدخول باستخدام GoogleSignIn API. سيتم دائمًا تسجيل الدخول عند إطلاق اللعبة. بدلاً من ذلك، استمِع إلى نتيجة محاولة تسجيل الدخول تلقائيًا باستخدام GamesSignInClient.isAuthenticated().

    GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(getActivity());

gamesSignInClient.isAuthenticated().addOnCompleteListener(isAuthenticatedTask -> {
  boolean isAuthenticated =
    (isAuthenticatedTask.isSuccessful() &&
     isAuthenticatedTask.getResult().isAuthenticated());

  if (isAuthenticated) {
    // Continue with Play Games Services
  } else {
    // Disable your integration with Play Games Services or show a
    // login button to ask  players to sign-in. Clicking it should
    // call GamesSignInClient.signIn().
  }
});

  2. قم بإزالة جميع المكالمات لتسجيل الخروج، حيث أصبحت إدارة الحساب ضمن الإعدادات الآن في نظام التشغيل وتطبيق "ألعاب Play".

  3. إذا تم تسجيل دخول اللاعب بنجاح، يمكنك إزالة زر تسجيل الدخول إلى "ألعاب Play" من لعبتك. إذا اختار المستخدم عدم تسجيل الدخول عند تشغيل اللعبة، يمكنك اختيار مواصلة عرض زر يحمل رمز "ألعاب Play" وبدء عملية تسجيل الدخول باستخدام GamesSignInClient.signIn().

  4. بعد التأكّد من تسجيل دخول المستخدم، يمكنك استرداد "معرّف المشغّل" لتحديد المستخدم.

    PlayGames.getPlayersClient(activity).getCurrentPlayer().addOnCompleteListener(mTask -> {
    // Get PlayerID with mTask.getResult().getPlayerId()
  }
);

  5. إزالة الاعتمادية على واجهة برمجة تطبيقات GoogleSignIn، إذا لم تعد قيد الاستخدام

تعديل أسماء فئات العملاء

عند إنشاء برامج (مثل LeaderboardsClient أو AchievementsClient)، استخدِم PlayGames.getFooClient() بدلاً من Games.getFooClient().

طلب الوصول من جهة الخادم

عند طلب الوصول من جهة الخادم، استخدِم GamesSignInClient.requestServerSideAccess() بدلاً من GoogleSignInAccount.getServerAuthCode().

GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(this);
gamesSignInClient
  .requestServerSideAccess(OAUTH_2_WEB_CLIENT_ID,
                           /*forceRefreshToken=*/ false)
  .addOnCompleteListener( task -> {
    if (task.isSuccessful()) {
      String serverAuthToken = task.getResult();
      // Send authentication code to the backend game server to be
      // exchanged for an access token and used to verify the
      // player via the Play Games Services REST APIs.
    } else {
      // Failed to retrieve authentication code.
    }
});

إزالة النطاقات الإضافية

مع الإصدار 2 من "خدمات ألعاب Play"، لا يمكنك طلب أي نطاقات إضافية. إذا كنت لا تزال بحاجة إلى طلب نطاقات إضافية، ننصحك باستخدام حزمة تطوير البرامج (SDK) لتسجيل الدخول بحساب Google إلى جانب "خدمات ألعاب Play".

نقل البيانات من GoogleApiClient

بالنسبة إلى عمليات الدمج الحالية الأقدم، قد تعتمد لعبتك على شكل واجهة برمجة التطبيقات GoogleApiClient API بحزمة SDK لخدمات "ألعاب Play". تم إيقاف هذه الميزة في أواخر عام 2017 واستبدالها بعملاء "غير متصلين". لإجراء عملية نقل البيانات، يمكنك استبدال الفئة GoogleApiClient بفئة "غير متصلة". بعد ذلك، عليك أيضًا اتّباع الإرشادات الموضَّحة أعلاه لنقل لعبتك من الإصدار 1 إلى الإصدار 2. فيما يلي تخطيط للفئات الشائعة:

com.google.android.gms.games.achievement.Achievements ->
    com.google.android.gms.games.AchievementsClient

com.google.android.gms.games.leaderboard.Leaderboard ->
    com.google.android.gms.games.LeaderboardsClient

com.google.android.gms.games.snapshot.Snapshots ->
    com.google.android.gms.games.SnapshotsClient

com.google.android.gms.games.stats.PlayerStats ->
    com.google.android.gms.games.PlayerStatsClient

com.google.android.gms.games.Players ->
    com.google.android.gms.games.PlayersClient

com.google.android.gms.games.GamesStatusCodes ->
    com.google.android.gms.games.GamesClientStatusCodes