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

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

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

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

1. نزِّل أحدث إصدار من إصدارات Google Play Plugins for Unity.
2. استورِد ملف .unitypackage من خلال اختيار خيار قائمة Unity IDE Assets > Import package > Custom Package واستيراد جميع العناصر.

ميزات Unity Editor

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

إعدادات الإنشاء

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

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

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

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

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

لتقليل حجم حزمة APK بشكل أكبر، افتح "مدير حِزم Unity" وأزِل أي حِزم غير مستخدَمة.

Quick Deploy

يمكن أن تقلّل ميزة "التشغيل السريع" حجم التطبيق الفوري المستند إلى 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

توفّر واجهة برمجة التطبيقات 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.
}