عمليات التثبيت المضمّنة في Google Play (متاجر التطبيقات الخارجية)

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

المتطلبات الأساسية

قبل دمج واجهة برمجة التطبيقات (API) لعمليات التثبيت المضمَّنة في متجر التطبيقات الخارجي، يجب إكمال الإعداد التالي في Google Play Console:

1. التسجيل في برنامج "الوصول إلى كتالوج Play": اتّبِع تعليمات التسجيل.
2. الموافقة على "الوصول إلى الكتالوج": سجِّل في برنامج "الوصول إلى الكتالوج" من خلال إعدادات Play Console.
3. استرداد رموز التسليم: عالِج عملية تصدير "كتالوج تطبيقات Play" التي تم تزويدك بها. تحتوي عملية التصدير هذه على catalog_token (رمز التسليم) الضروري لكل تطبيق مؤهَّل لتوزيعه.

المتطلبات

لكي تظهر الواجهة النصفية للمستخدمين بنجاح، يجب استيفاء المتطلبات التالية:

• يجب أن يكون المستخدم مقيمًا في الولايات المتحدة.
• يجب أن يكون الحد الأدنى لإصدار Google Play على الجهاز هو 52.3.
• يجب أن يكون مستوى واجهة برمجة تطبيقات Android 24 أو أعلى.
• يجب تقديم catalog_token صالح وغير منتهي الصلاحية للوصول إلى "متجر Google Play".

استدعاء عمليات التثبيت المضمَّنة من متجر التطبيقات

لاستدعاء الواجهة النصفية لعمليات التثبيت المضمَّنة، أنشِئ مثيلاً لفئة Intent التي تستهدف عنوان URL للرابط المؤدي إلى صفحة معيّنة في Google Play وتتضمّن catalog_token الفريد.

استخدِم نموذج الرمز البرمجي التالي (Kotlin أو Java) كإرشاد:

val intent = Intent(Intent.ACTION_VIEW)
val referrer = "<Your referrer string>"
val id = "<Package name of the app to be installed>"
val callerId = "<Package name of your third-party app store>"

// Retrieve the app-specific token from your processed catalog export
val catalogToken = getVerificationTokenByDocId(id)

intent.setPackage("com.android.vending")
val deepLinkUrl = "https://play.google.com/d?id=$id&referrer=$referrer"
intent.data = Uri.parse(deepLinkUrl)

// Set the required intent extras
intent.putExtra("overlay", true)
intent.putExtra("callerId", callerId)
intent.putExtra("catalog_token", catalogToken)

val packageManager = context.getPackageManager()
if (intent.resolveActivity(packageManager) != null) {
  startActivityForResult(intent, 0) // Call with a request code to receive ActivityResults
}

Intent intent = new Intent(Intent.ACTION_VIEW);
String referrer = "<Your referrer string>";
String id = "<Package name of the app to be installed>";
String callerId = "<Package name of your third-party app store>";

// Retrieve the app-specific token from your processed catalog export
byte[] catalogToken = getVerificationTokenByDocId(id);

intent.setPackage("com.android.vending");
String deepLinkUrl = "https://play.google.com/d?id=" + id + "&referrer=" + referrer;
intent.setData(Uri.parse(deepLinkUrl));

// Set the required intent extras
intent.putExtra("overlay", true);
intent.putExtra("callerId", callerId);
intent.putExtra("catalog_token", catalogToken);

PackageManager packageManager = context.getPackageManager();
if (intent.resolveActivity(packageManager) != null) {
  startActivityForResult(intent, 0); // Call with a request code to receive ActivityResults
}

مَعلمات واجهة برمجة التطبيقات (API) لعمليات التثبيت المضمَّنة

يجب تمرير المَعلمات التالية في عنوان URL لـ Intent أو كـ Intent Extras من أجل منح الإذن بعملية التثبيت المضمَّنة:

(اختياري) ميزة "التثبيت المضمَّن في Google Play" مع تراكب حالة التثبيت

لعرض تراكب حالة التثبيت مع عملية التثبيت المضمَّنة، عليك دمج ميزة "التثبيت المضمَّن في Google Play" مع ميزة "الوسيلة الثابتة" باستخدام حزمة تطوير البرامج (SDK) لـ Google Play HSDP.

لكي يظهر تدفق التثبيت المضمَّن مع التلميحات المرئية الثابتة، يجب استيفاء الشروط التالية:

• يجب أن يكون الحد الأدنى لإصدار "متجر Google Play" على الجهاز المستهدَف هو 52.6 أو أعلى.
• يجب أن يكون مستوى واجهة برمجة تطبيقات Android 24 (Android M) أو أعلى.
• يجب إجراء عملية الدمج مع حزمة تطوير البرامج (SDK) لـ HSDP بالإصدار 2.1.0 أو أعلى.

مثال على عملية الدمج

// Step 1: Initialize HSDP Service
// Note: Calling create(activity) automatically configures useServiceBasedHsdp = false
// (Activity Path) under the hood without requiring manual boolean flags.
val hsdpService = HsdpDeepLinkServiceFactory.create(activity)

// Step 2: Construct Extra Query Parameters with Catalog Token
val extraQueryParams = mapOf("catalog_token" to "YOUR_SECURE_CATALOG_TOKEN_VALUE")

// Step 3: Trigger Inline Install Flow
hsdpService.open(
    targetAppPackageName = "com.example.targetapp",
    referrer = "3pas_ad_campaign_123",
    listener = object : HsdpDeepLinkServiceListener {
        override fun onDeepLinkStarted() {
            // Inline details dialog started successfully
        }
        override fun onAffordanceStarted() {
            // HPOA persistent affordance UI attached
        }
        override fun onAffordanceEnded() {
            // Affordance UI detached
        }
        override fun onError(errorMessage: String) {
            // Handle error or fallback
        }
    },
    extraQueryParams = extraQueryParams
)

مثال على إيقاف تتبُّع الوسيلة

يسمح هذا الرمز البرمجي للتطبيق المتصل بإيقاف تتبُّع حالة التثبيت يدويًا وإغلاق تراكب HPOA. ملاحظة: لن يؤدي هذا الإجراء إلى إغلاق ورقة التثبيت الخاصة بـ HSDP نفسها، بل سيؤدي فقط إلى إغلاق الوسيلة.

// Stop tracking the installation state and dismiss the affordance overlay
hsdpService.stopAffordance(
    targetAppPackageName = "com.example.targetapp",
    listener = object : HsdpDeepLinkService.AffordanceListener {
        override fun onAffordanceStopped() {
            // Affordance overlay stopped successfully
        }
    }
)

حالات التلميحات المرئية وتجربة المستخدم

تتضمّن ميزة "التثبيت المضمَّن في Google Play" مع ميزة "الوسيلة الثابتة" حالتين مرئيتَين:

1. حالة "جارٍ التثبيت": تعرض صورة مصغّرة للتطبيق المستهدَف ومؤشرًا لتقدُّم عملية التثبيت. عند النقر على الصورة المصغّرة، تتم إعادة فتح ورقة التثبيت الخاصة بـ HSDP.
2. حالة "بعد التثبيت": تعرض رمز التطبيق المستهدَف مع إجراء "فتح". عند النقر على الصورة المصغّرة، يتم فتح التطبيق المثبّت حديثًا.

جارٍ التثبيت	بعد التثبيت