התקנות ישירות ב-Google Play (חנויות אפליקציות של צד שלישי)

בדף הזה מוסבר איך חנויות אפליקציות של צד שלישי שנרשמו לתוכנית Catalog Access יכולות לשלב התקנות ישירות של 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.
• רמת ה-API של Android צריכה להיות 24 ומעלה.
• כדי לגשת לחנות Play, צריך לספק catalog_token תקף שלא פג תוקפו.

הפעלת התקנות מוטבעות מחנות האפליקציות

כדי להפעיל את ההתקנה מהאתר, יוצרים מופע של המחלקה Intent שמטרגטת את כתובת הקישור העמוק של 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
}

פרמטרים של Inline Install API

כדי לאשר את ההתקנה בתוך האפליקציה, צריך להעביר את הפרמטרים הבאים בכתובת ה-URL של ה-Intent או כ-Intent Extras:

(אופציונלי) התקנה מתוך האפליקציה ב-Google Play עם שכבת-על של סטטוס ההתקנה

כדי להציג שכבת-על של סטטוס ההתקנה בתהליך ההתקנה מהאתר, צריך לשלב את התכונה 'התקנה מהאתר' של Google Play עם התכונה 'אמצעי גישה קבוע' באמצעות Google Play HSDP SDK.

כדי שתהליך ההתקנה מהאתר יופיע עם מזמינוּת קבועה:

• גרסת חנות Google Play במכשיר היעד צריכה להיות 52.5 ומעלה.
• רמת ה-API ב-Android צריכה להיות 24 (Android M) ומעלה.
• משלבים עם HSDP SDK בגרסה 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
)

דוגמה להפסקת מעקב אחר אפשרויות פעולה

מאפשר לאפליקציה המתקשרת להפסיק באופן ידני את המעקב אחר מצב ההתקנה ולסגור את שכבת העל של 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
        }
    }
)

מצבי Affordance וחוויית משתמש

לתכונה 'התקנה מתוך האפליקציה ב-Google Play' עם האפשרות המתמשכת יש שני מצבים חזותיים:

1. מצב ההתקנה: מוצגת תמונה ממוזערת של אפליקציית היעד וסמל התקדמות ההתקנה. לחיצה על התמונה הממוזערת מפעילה מחדש את גיליון ההתקנה של HSDP.
2. מצב אחרי ההתקנה: מוצג סמל האפליקציה הרלוונטית עם הפעולה 'פתיחה'. לחיצה על התמונה הממוזערת פותחת את האפליקציה שהותקנה.

התקנה	אחרי ההתקנה