استخدام "تطبيقات Google Play الفورية" مع Unity

يعمل المكوّن الإضافي لتطبيقات Google Play الفورية على Unity على ضبط مشروع Unity لإنشاء إصدار فوري من التطبيق للعبتك. يصف هذا الدليل كيفية تثبيت هذا المكون الإضافي واستخدامه.

تنزيل المكوّن الإضافي واستيراده

المكوّن الإضافي هو جزء من مكوّنات Google Play الإضافية لـ Unity. لاستيراد المكون الإضافي، اتبع الخطوات التالية:

  1. نزِّل أحدث إصدار من إصدارات Google Play الإضافية لإصدارات Unity.
  2. استورِد ملف .unitypackage عن طريق تحديد خيار قائمة Unity IDE مواد العرض > استيراد الحزمة > الحزمة المخصصة واستيراد جميع العناصر.

ميزات Unity Editor

استورِد المكوّن الإضافي لإضافة القائمة الفرعية Google > Play Instant في Unity. توفر هذه القائمة الفرعية الخيارات التالية.

إعدادات الإصدار

يؤدي هذا الاختصار إلى فتح نافذة تتيح التبديل بين وضعَي التطوير المثبَّت والبحث الفوري. يؤدي التبديل إلى البحث الفوري إلى تنفيذ التغييرات التالية:

  • تنشئ رمزًا لتعريف النصوص البرمجية يُسمى PLAY_INSTANT ويمكن استخدامه للنصوص البرمجية مع #if PLAY_INSTANT و#endif.
  • إدارة تحديثات ملف AndroidManifest.xml لتغييرات معيّنة مطلوبة مثل android:targetSandboxVersion.

إعدادات المشغّل

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

وتتضمّن الاقتراحات المحدّدة استخدام OpenGL ES 2.0 فقط وإيقاف ميزة "العرض المتعدّد السلاسل".
الشكل 1. مربع الحوار إعدادات المشغّل

تنقسم إعدادات المشغّل هذه إلى إعدادات مطلوبة ومقترَحة. إذا كان الإعداد يحتوي على زر Update مقابل، انقر عليه لتغيير الإعداد إلى القيمة المفضّلة.

لتقليل حجم حزمة APK، افتح Unity Package Manager وأزِل أي حزم غير مستخدمة.

النشر السريع

يمكن لميزة "النشر السريع" تقليل حجم التطبيق الفوري المستند إلى Unity عن طريق تجميع بعض مواد العرض في AssetBundle. عند استخدام ميزة "النشر السريع"، يتم تجميع محرك ألعاب Unity وشاشة التحميل في حزمة APK لتطبيق فوري، وبعد بدء تشغيل التطبيق الفوري يتم استرداد AssetBundle من الخادم.

عمليات تثبيت الدعم

الهدف من العديد من التطبيقات الفورية هو منح المستخدمين فرصة لتجربة التطبيق قبل تثبيت الإصدار الكامل. يوفّر المكوّن الإضافي لتطبيقات Google Play الفورية لـ Unity واجهات برمجة تطبيقات لعرض مربّع حوار التثبيت من "متجر Play" ونقل الحالة من التطبيق الفوري إلى التطبيق المثبّت.

إظهار طلب التثبيت

يمكن لتطبيق فوري مزوّد بزر تثبيت أن يعرض مربّع حوار للتثبيت على "متجر Play" من خلال استدعاء ما يلي من معالج نقرات على زرّ التثبيت:

Google.Play.Instant.InstallLauncher.ShowInstallPrompt();

تتضمّن الطريقة ShowInstallPrompt() حمل زائد يسمح بواحد أو أكثر مما يلي:

  • تحديد ما إذا كان المستخدم يلغي عملية التثبيت أم لا. إلغاء onActivityResult() في النشاط الرئيسي للتطبيق الفوري والبحث عن RESULT_CANCELED في requestCode المحدّد
  • تمرير سلسلة مُحيل التثبيت من خلال المَعلمة referrer
  • حالة التمرير بجلسة اللعبة الحالية من خلال PutPostInstallIntentStringExtra().

نوضح هذه الأمور في المثال التالي:

using Google.Play.Instant;
...
const int requestCode = 123;
var sessionInfo = /* Object serialized as a string representing player's current location, etc. */;
using (var activity = UnityPlayerHelper.GetCurrentActivity())
using (var postInstallIntent = InstallLauncher.CreatePostInstallIntent(activity))
{
    InstallLauncher.PutPostInstallIntentStringExtra(postInstallIntent, "sessionInfo", sessionInfo);
    InstallLauncher.ShowInstallPrompt(activity, requestCode, postInstallIntent, "test-referrer");
}

إذا أكمل المستخدم تثبيت التطبيق، سيعيد "متجر Play" تشغيل التطبيق باستخدام postInstallIntent المقدَّم. يمكن للتطبيق المثبّت استرداد قيمة تم تحديدها في postInstallIntent باستخدام ما يلي:

var sessionInfo = InstallLauncher.GetPostInstallIntentStringExtra("sessionInfo");

ملاحظات:

  • قد لا تصل الإضافات المضمَّنة في postInstallIntent إلى التطبيق المثبّت إذا ثبّت المستخدم التطبيق ولكنه ألغى عملية إطلاق التطبيق بعد التثبيت. يتناسب تمرير الأهداف الإضافية مع الاحتفاظ بحالة الجلسة النشطة مقارنةً بالاحتفاظ بالحالة المستمرة. ولمراجعة الفقرة الأخيرة يُرجى الاطّلاع على Cookie API.
  • يمكن لأي شخص إنشاء هدف بحقول إضافية لتشغيل التطبيق المثبّت، ولذلك إذا كانت الحمولة تمنح شيئًا ذا قيمة، صمِّم الحمولة بحيث يمكن استخدامها مرة واحدة فقط، وتوقيعها بطريقة مشفّرة، والتحقق من توقيعها على الخادم.

توفّر Cookie API طرقًا لتمرير ملف تعريف ارتباط (على سبيل المثال، رقم تعريف اللاعب أو بيانات إكمال المستوى) من تطبيق فوري إلى التطبيق المثبّت المقابل له. وعلى عكس إضافات postInstallIntent، تتوفر حالة ملف تعريف الارتباط حتى إذا لم يشغّل المستخدم التطبيق المثبَّت فورًا. على سبيل المثال، يمكن لتطبيق فوري طلب الرمز التالي من معالج النقر على زر التثبيت:

using Google.Play.Instant;
...
var playerInfo = /* Object serialized as a string representing game levels completed, etc. */;
var cookieBytes = System.Text.Encoding.UTF8.GetBytes(playerInfo);
try
{
    var maxCookieSize = CookieApi.GetInstantAppCookieMaxSize();
    if (cookieBytes.Length > maxCookieSize)
    {
        UnityEngine.Debug.LogErrorFormat("Cookie length {0} exceeds limit {1}.", cookieBytes.Length, maxCookieSize);
    }
    else if (CookieApi.SetInstantAppCookie(cookieBytes))
    {
        UnityEngine.Debug.Log("Successfully set cookie. Now display the app install dialog...");
        InstallLauncher.ShowInstallPrompt();
    }
    else
    {
        UnityEngine.Debug.LogError("Failed to set cookie.");
    }
}
catch (CookieApi.InstantAppCookieException ex)
{
    UnityEngine.Debug.LogErrorFormat("Failed to set cookie: {0}", ex);
}

إذا أكمل المستخدم تثبيت التطبيق، يمكن للتطبيق المثبّت استرداد بيانات ملفات تعريف الارتباط باستخدام الرمز التالي:

var cookieBytes = CookieApi.GetInstantAppCookie();
var playerInfoString = System.Text.Encoding.UTF8.GetString(cookieBytes);
if (!string.IsNullOrEmpty(playerInfoString))
{
    // Initialize game state based on the cookie, e.g. skip tutorial level completed in instant app.
}