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

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

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

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

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

المتطلبات

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

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

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

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

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

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

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

• يجب أن يكون الحد الأدنى لإصدار "متجر Google Play" على الجهاز المستهدَف هو 52.5 أو إصدار أحدث.
• يجب أن يكون مستوى واجهة برمجة التطبيقات في Android هو 24 (Android M) أو أعلى.
• نفِّذ عملية تكامل مع حزمة تطوير البرامج (SDK) من HSDP بالإصدار 2.0.2 (قريبًا) أو إصدار أحدث.

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

// 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
)

مثال على إيقاف تتبُّع عناصر التفاعل

يسمح هذا الإذن للتطبيق المتصل بإيقاف تتبُّع حالة التثبيت يدويًا وإغلاق العناصر المركّبة التي تشير إلى حالة الإيقاف المؤقت. ملاحظة: لن يؤدي هذا الإجراء إلى إغلاق ورقة تثبيت 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. حالة ما بعد التثبيت: تعرض رمز التطبيق المستهدَف مع إجراء "فتح". يؤدي النقر على الصورة المصغّرة إلى فتح التطبيق المثبّت حديثًا.

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