دمج واجهة برمجة التطبيقات PGS Recall في لعبتك

تشرح هذه الصفحة كيفية تنفيذ Recall API في لعبتك. يتناول أولاً إعداد خادم وعميل اللعبة لدعم ثم ننتقل إلى كيفية تخزين الرموز المميزة واستردادها.

إعداد خادم اللعبة

يمكنك إعداد خادم لعبتك لإرسال طلبات البيانات من واجهة برمجة التطبيقات Recall إلى خوادم Google.

1. إعداد مشروعك على "خدمات ألعاب Play"

(إذا لم يسبق لك إكمال هذا الإجراء) اتّبِع التعليمات الواردة في إعداد Google Play. "خدمات الألعاب":

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

2. إعداد حساب خدمة للعبة

اتبع التعليمات الخاصة بإنشاء خدمة الحساب. في النهاية، من المفترض أن يكون لديك ملف JSON به بيانات اعتماد حساب الخدمة.

ملاحظة: Recall API هي واجهة برمجة تطبيقات مجرّد خادم إلى خادم. لهذا السبب، يسعى الاستدعاء تستخدم واجهة برمجة التطبيقات حسابات الخدمة لمصادقة خادم اللعبة ولا تستخدم الإعدادات العادية بروتوكول OAuth الثلاثي الذي تستخدمه واجهة برمجة التطبيقات للألعاب الأخرى لمصادقة كلا خادمي اللعبة والمستخدمين النهائيين

3- تنزيل مكتبة Java من جهة الخادم لتطبيق PlayGamesServices

نزِّل أحدث ألعاب Google API-services المكتبة وقم بتحميله إلى خادمك.

4. إعداد بيانات الاعتماد الخاصة باستدعاءات واجهة برمجة التطبيقات Recall

راجِع مقالة الاستعداد لإنشاء واجهة برمجة تطبيقات معتمَدة. مكالمة للحصول على مزيد من السياق.

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.games.Games;
import com.google.api.services.games.GamesScopes;

// ...

GoogleCredential credential =
  GoogleCredential.fromStream(new FileInputStream("<credentials>.json"))
    .createScoped(Collections.singleton(GamesScopes.ANDROIDPUBLISHER));

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

إعداد برنامج اللعبة

عليك إعداد برنامج اللعبة لاسترداد معرّفات جلسات الاستدعاء التي يستخدمها الخادم. على الاتصال بخوادم Google.

حزمة تطوير البرامج (SDK) بلغة Java

إعداد حزمة تطوير البرامج (SDK) بلغة Java في البرنامج احرص على تضمين com.google.android.gms:play-services-games-v2:19.0.0 وcom.google.android.gms:play-services-tasks:18.0.2 أو أكثر في Gradle.

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

Kotlin

PlayGames.getRecallClient(getActivity())
                .requestRecallAccess()
                .addOnSuccessListener { recallAccess -> val recallSessionId: String = recallAccess.getSessionId() }
                // Send the recallSessionId to your game server

Java

PlayGames.getRecallClient(getActivity())
  .requestRecallAccess()
  .addOnSuccessListener(
    recallAccess -> {
      String recallSessionId = recallAccess.getSessionId();
      // Send the recallSessionId to your game server
    });

Unity SDK

عليك إعداد حزمة تطوير البرامج (SDK) في Unity ضمن البرنامج.

للاتصال بخوادم Google بالمعلومات الصحيحة، يجب عليك اطلب معرِّف جلسة Recall من حزمة تطوير البرامج (SDK) للعميل، ثم أرسِله إلى حزمة SDK الخاصة باللعبة الخادم.

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // Send the recallSessionId to your game server
    });

استخدام Recall API في خادم لعبتك

وبعد إعداد الخادم والعميل، يمكنك إرسال recallSessionID من عميل اللعبة إلى خادم اللعبة، واتبع الإرشادات أدناه لبدء باستخدام واجهة برمجة تطبيقات Java لتخزين الرموز المميزة لاستدعاء الرموز من جانب الخادم أو استردادها أو حذفها.

الرموز المميّزة للمتجر

المستخدِمين يمكن تخزين الرمز المميّز للّعبة والشخصية باستخدام LinkPersonaRequest . يجب استخدام GoogleCredential لاستدعاء Google APIs (راجع الاتصال Google واجهات برمجة التطبيقات للسياق). يُرجى العلم أنّه وفقًا للعدد القيم الفريدة للسمة 1:1 قيدًا، يمكنك ربط شخصية واحدة فقط إلى ملف شخصي واحد على "خدمات ألعاب Play" في كل مرة (والعكس صحيح).يجب ضبط درجة الدقة في حال سبق وتمّ ربط هذا الملف الشخصي على "خدمات ألعاب Play" بشخصية أخرى.

يمكنك اختياريًا ضبط مدة بقاء (TTL) على الرمز المميّز مع توضيح مدة فإن الرمز صالح باستخدام المدد . ويمكنك اختيار تعيين هذا باستخدام SetTtl() (كما هو موضح أدناه)، التي تحدد تاريخ انتهاء الصلاحية من مقدار الوقت المحدد في الطريقة setExpireTime()، ما يتيح لك تحديد وقت دقيق لانتهاء صلاحية الرموز المميّزة

يجب تشفير الشخصية والرمز المميّز للّعبة، ولا يمكن تضمينهما في البيانات الشخصية. معلومات التعريف الشخصية. يمكن أن تكون سلاسل الشخصية والرمز المميز 256 كحد أقصى ويمكن أن يكون هناك 20 رمزًا أو شخصية مخزنة على الأكثر لاعب في كل مباراة.

يمكن تخزين رمز مميّز واحد فقط لكل شخصية لكل لاعب في وقت محدَّد. جارٍ محاولة بتخزين رمز مميز آخر بنفس الشخصية بدلاً من الرمز الأصلي.

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

ملاحظة: يجب أن تتضمّن الرموز المميزة التي تم إنشاؤها للمستخدمين الذين لا يملكون ملفات شخصية مدة بقاء افتراضية تبلغ 30 يومًا. وبخلاف ذلك، بالنسبة إلى المستخدمين الذين لديهم ملفات شخصية في "خدمات ألعاب Play"، لا يمكن الرموز المميزة مدة البقاء (TTL) التلقائية.

import com.google.api.services.games.Games.Recall.LinkPersona;
import com.google.api.services.games.model.LinkPersonaRequest;
import com.google.api.services.games.model.LinkPersonaResponse;
import com.google.protobuf.util.Durations;

// ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

String recallSessionId = ... // recallSessionID from game client
String persona = ... // encrypted opaque string, stable for in-game account
String token = ... // encrypted opaque string encoding the progress line

LinkPersonaRequest linkPersonaRequest =
  LinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    .setToken(token)
    .setCardinalityConstraint(ONE_PERSONA_TO_ONE_PLAYER)
    .setConflictingLinksResolutionPolicy(CREATE_NEW_LINK)
    .setTtl(Durations.fromDays(7)) // Optionally set TTL for token
    .build();

LinkPersonaResponse linkPersonaResponse =
  gamesApi.recall().linkPersona(linkPersonaRequest).execute();

if (linkPersonaResponse.getState() == LINK_CREATED) {
  // success
}

استرداد الرموز المميزة

تتوفّر ثلاثة خيارات لاسترداد رمز مميّز استنادًا إلى ألعابك. احتياجاتهم. يمكنك اطلب ما يلي:

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

ملاحظة: عند طلب رموز Recall المميّزة، لا تعرض واجهة برمجة التطبيقات السلاسل التي لتمثيل الشخصية.

الرموز المميّزة لتذكُّر بيانات الألعاب على مستوى اللعبة

لاسترداد الرموز المميّزة للتذكُّر من اللعبة الحالية، يجب الحصول على recallSessionId من العميل وتمريره إلى retrieveTokens API:

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrievePlayerTokensResponse;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrievePlayerTokensResponse retrievePlayerTokensResponse =
  gamesApi.recall().retrieveTokens(recallSessionId).execute();

for (RecallToken recallToken : retrievePlayerTokensResponse.getTokens()) {
  String token recallToken.getToken();
  // Same string as was written in LinkPersona call
  // decrypt and recover in-game account
}

أحدث رمز مميّز لتذكُّر بيانات الألعاب في جميع الألعاب التي يمتلكها حساب المطوِّر

لاسترداد أحدث رمز مميّز مخزَّن في جميع الألعاب التي يملكها المطوِّر في Google Play Console، عليك الحصول على recallSessionId من العميل وإدخاله إلى lastTokenFromAllDeveloperGames API، كما هو موضح في مقتطف الرمز التالي. كجزء من الرد، يمكنك فحص رقم تعريف التطبيق المرتبط باستخدام هذا الرمز.

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveDeveloperGamesLastPlayerTokenResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrieveDeveloperGamesLastPlayerTokenResponse response =
        gamesApi.recall().lastTokenFromAllDeveloperGames(recallSessionId)
        .execute();

if (response.hasGamePlayerToken()) {
    GamePlayerToken gamePlayerToken = response.getGamePlayerToken();

    // The ID of the application that the token is associated with.
    String applicationId = gamePlayerToken.getApplicationId();

    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

جميع رموز Recall المميّزة في قائمة معيّنة من الألعاب التي يملكها حساب المطوِّر

لاسترداد جميع الرموز المميزة المرتبطة بقائمة ألعاب يملكها حساب المطوّر الخاص بك في Google Play Console، يمكنك الحصول على recallSessionId من العميل وتمريره إلى gamesPlayerTokens API. إدخال تتضمن أرقام تعريف التطبيقات.

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveGamesPlayerTokensResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

// Application IDs for which you would like to retrieve the recall tokens.
List<String> applicationIds = ...

RetrieveGamesPlayerTokensResponse response =
gamesApiClient
        .recall()
        .gamesPlayerTokens(recallSessionId)
        .setApplicationIds(applicationIds)
        .execute();

for (GamePlayerToken gamePlayerToken : response.getGamePlayerTokens()) {
    // The ID of the application that the token is associated with.
    String applicationId  = gamePlayerToken.getApplicationId();


    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();
    
    // Decrypt and recover in-game account.
}

حذف الرمز المميّز لتذكُّر بيانات الألعاب

وإذا لزم الأمر، يمكنك أيضًا حذف الرمز المميّز لتذكُّر بيانات الألعاب من خلال إجراء المكالمة التالية:

import com.google.api.services.games.Games;
import com.google.api.services.games.model.UnlinkPersonaRequest;
import com.google.api.services.games.model.UnlinkPersonaResponse;

// ...

String recallSessionId = ...
String persona = ...
String token = ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

UnlinkPersonaRequest unlinkPersonaRequest =
  UnlinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    // .setToken(token) - alternatively set token, but not both
    .build();

UnlinkPersonaResponse unlinkPersonaResponse =
  gamesApi.recall().unlinkPersona(unlinkPersonaRequest).execute();

boolean unlinked = unlinkPersonaResponse.isUnlinked();

تفعيل وضع "بدون ملف شخصي"

يمكنك تفعيل وظائف Recall API محدودة. للمستخدمين الذين ليس لديهم ملفات شخصية على "خدمات ألعاب Play" باتّباع الخطوات التالية:

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

<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

البنود الإضافية

بالإضافة إلى الخضوع لبنود "خدمات ألعاب Play" "الخدمة"، أنت توافق على أنه في استخدام Recall API للمستخدمين الذين ليس لديهم ملف شخصي على "خدمات ألعاب Play"، ما يتيح مشاركة بيانات المستخدم النهائي لدى Google بدون أن يكون لديه ملف شخصي على "خدمات ألعاب Play"، قبل مشاركة هذه البيانات مع Google، عليك تزويد المستخدم إشعار مناسب يصف 1) مشاركتك للبيانات مع Google لتمكين ألعاب Play ميزة ربط الحساب، 2) توافر الإعدادات المراد إدارتها مثل تلك التي تتم مشاركتها ضمن إعدادات "ألعاب Play" 3) معالجة هذه البيانات بموجب سياسة خصوصية Google السياسة والحصول على مستخدم نهائي مناسب الموافقة على هذه المشاركة التي تستوفي جميع المتطلبات القانونية السارية.