نصب‌های درون‌خطی گوگل پلی (فروشگاه‌های اپلیکیشن شخص ثالث)

این صفحه توضیح می‌دهد که چگونه فروشگاه‌های اپلیکیشن شخص ثالث ثبت‌شده در برنامه Catalog Access می‌توانند نصب‌های درون‌خطی Google Play را ادغام کنند، ویژگی‌ای که به فروشگاه‌های اپلیکیشن اندروید شخص ثالث در ایالات متحده اجازه می‌دهد تا کاربران را به دانلود برنامه‌های Play از طریق Google Play با همان شرایطی که هر دانلود دیگری که مستقیماً از طریق فروشگاه Google Play انجام می‌شود، هدایت کنند.

پیش‌نیازها

قبل از ادغام API نصب درون‌خطی در فروشگاه برنامه شخص ثالث خود، باید تنظیمات زیر را در کنسول Google Play انجام دهید:

1. ثبت نام در برنامه دسترسی به کاتالوگ بازی: دستورالعمل‌های ثبت نام را دنبال کنید.
2. ثبت‌نام برای دسترسی به کاتالوگ: از طریق تنظیمات کنسول Play خود، در برنامه دسترسی به کاتالوگ ثبت‌نام کنید.
3. بازیابی توکن‌های تحویل: خروجی کاتالوگ برنامه Play که به شما ارائه شده است را پردازش کنید. این خروجی شامل catalog_token لازم (توکن تحویل) برای هر برنامه‌ای است که واجد شرایط توزیع آن هستید.

الزامات

برای اینکه رابط کاربری نیم‌صفحه با موفقیت برای کاربران نمایش داده شود، باید شرایط زیر رعایت شود:

• کاربر باید در ایالات متحده مستقر باشد.
• حداقل نسخه گوگل پلی روی دستگاه باید ۵۲.۳ باشد.
• سطح API اندروید باید ۲۴ یا بالاتر باشد.
• برای دسترسی به فروشگاه Play، باید یک catalog_token معتبر و منقضی نشده ارائه دهید.

نصب‌های درون‌برنامه‌ای را از فروشگاه برنامه خود فراخوانی کنید

برای فراخوانی نیم‌صفحه نصب درون‌خطی، یک نمونه از کلاس Intent ایجاد کنید که URL لینک عمیق گوگل پلی را هدف قرار می‌دهد و شامل catalog_token منحصر به فرد شما می‌شود.

از کد نمونه زیر (کاتلین یا جاوا) به عنوان راهنما استفاده کنید:

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 نصب درون خطی

پارامترهای زیر باید در Intent URL یا به عنوان Intent Extras برای تأیید نصب درون‌خطی ارسال شوند:

(اختیاری) نصب درون‌خطی گوگل پلی به همراه نمایش وضعیت نصب

برای نمایش وضعیت نصب در کنار جریان نصب درون‌برنامه‌ای، باید نصب درون‌برنامه‌ای گوگل پلی را با ویژگی Persistent Affordance با استفاده از SDK گوگل پلی HSDP ادغام کنید.

برای اینکه جریان نصب درون‌خطی با قابلیت دسترسی پایدار ظاهر شود:

• حداقل نسخه گوگل پلی استور دستگاه هدف باید ۵۲.۵ یا بالاتر باشد.
• سطح API اندروید باید ۲۴ (اندروید M) یا بالاتر باشد.
• با HSDP SDK نسخه ۲.۰.۲ (به زودی) یا بالاتر ادغام شود.

مثال ادغام

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

مثال ردیابی affordance را متوقف کنید

به برنامه تماس‌گیرنده اجازه می‌دهد تا ردیابی وضعیت نصب را به صورت دستی متوقف کرده و پوشش HPOA را رد کند. توجه: این کار خود برگه نصب HSDP را رد نمی‌کند، فقط affordance را رد می‌کند.

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

ایالت‌های مقرون‌به‌صرفه و تجربه کاربری

نصب درون‌خطی گوگل پلی با قابلیت Persistent Affordance دو حالت بصری دارد:

1. وضعیت نصب : یک تصویر کوچک از برنامه هدف و یک نشانگر پیشرفت نصب نمایش داده می‌شود. کلیک بر روی تصویر کوچک، صفحه نصب HSDP را مجدداً اجرا می‌کند.
2. وضعیت پس از نصب : آیکون برنامه‌ی هدف را با عملکرد «باز کردن» نمایش می‌دهد. با کلیک بر روی تصویر کوچک، برنامه‌ی تازه نصب شده باز می‌شود.

نصب	پس از نصب