کتابخانه ارجاع‌دهنده نصب Play

می‌توانید از Install Referrer API «فروشگاه Google Play» برای بازیابی ایمن محتوای ارجاعی از Google Play استفاده کنید. کتابخانه کارخواه Play Install Referrer API به زبان برنامه‌نویسی Java نوشته شده است و پوششی برای فایل «زبان تعریف میانای Android»‏ (AIDL) است که میانا را برای سرویس Install Referrer تعریف می‌کند. می‌توانید از کتابخانه کارخواه Play Install Referrer API برای ساده کردن فرایند توسعه استفاده کنید.

این راهنما اصول بازیابی اطلاعات ارجاعی از Google Play را بااستفاده از «کتابخانه ارجاع‌دهنده نصب Play» پوشش می‌دهد.

توجه: اگر برنامه‌تان را بااستفاده از زبانی غیراز زبان برنامه‌نویسی Kotlin یا Java توسعه می‌دهید، می‌توانید بااستفاده از Play Install Referrer API مستقیماً با فایل AIDL تعامل داشته باشید.

درحال به‌روزرسانی وابستگی‌های برنامه

خط زیر را به بخش وابستگی‌های فایل build.gradle برای برنامه‌تان اضافه کنید:

شیک

dependencies {
    ...
    implementation "com.android.installreferrer:installreferrer:2.2"
}

کاتلین

dependencies {
    ...
    implementation("com.android.installreferrer:installreferrer:2.2")
}

درحال اتصال به Google Play

قبل‌از اینکه بتوانید از «کتابخانه Play Install Referrer API» استفاده کنید، باید بااستفاده از مراحل زیر، اتصالی به برنامه «فروشگاه Play» برقرار کنید:

1. برای ایجاد نمونه‌ای از کلاس InstallReferrerClient ، روش newBuilder() را فراخوانی کنید.

2. برای برقراری اتصال به Google Play، startConnection() را فراخوانی کنید.

3. روش startConnection() غیرهم‌زمان است، بنابراین باید InstallReferrerStateListener را لغو کنید تا پس‌از تکمیل startConnection() فراخوانی دریافت کنید.

4. روش onInstallReferrerSetupFinished() را لغو کنید تا پس‌از تکمیل فراخوانی به شما اطلاع داده شود. این روش با کد پاسخی فراخوانی می‌شود که باید از آن برای مدیریت حالت‌های مختلف استفاده کنید. OK نشان می‌دهد که اتصال موفقیت‌آمیز بوده است. هرکدام از ثابت‌های دیگر InstallReferrerResponse برای انواع مختلف خطاها هستند.

5. روش onInstallReferrerServiceDisconnected() را لغو کنید تا اتصالات قطع‌شده به Google Play را مدیریت کنید. برای مثال، اگر سرویس «فروشگاه Play» در پس‌زمینه درحال به‌روزرسانی باشد، ممکن است اتصال کارخواه «کتابخانه ارجاع‌دهنده نصب Play» قطع شود. کلاینت کتابخانه باید روش startConnection() را فراخوانی کند تا اتصال را قبل‌از ارسال درخواست‌های بیشتر بازراه‌اندازی کند.

کد زیر نحوه شروع و آزمایش اتصال به برنامه «فروشگاه Play» را نشان می‌دهد:

کاتلین

private lateinit var referrerClient: InstallReferrerClient

referrerClient = InstallReferrerClient.newBuilder(this).build()
referrerClient.startConnection(object : InstallReferrerStateListener {

    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        when (responseCode) {
            InstallReferrerResponse.OK -> {
                // Connection established.
            }
            InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> {
                // API not available on the current Play Store app.
            }
            InstallReferrerResponse.SERVICE_UNAVAILABLE -> {
                // Connection couldn't be established.
            }
        }
    }

    override fun onInstallReferrerServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
})

جاوا

InstallReferrerClient referrerClient;

referrerClient = InstallReferrerClient.newBuilder(this).build();
referrerClient.startConnection(new InstallReferrerStateListener() {
    @Override
    public void onInstallReferrerSetupFinished(int responseCode) {
        switch (responseCode) {
            case InstallReferrerResponse.OK:
                // Connection established.
                break;
            case InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
                // API not available on the current Play Store app.
                break;
            case InstallReferrerResponse.SERVICE_UNAVAILABLE:
                // Connection couldn't be established.
                break;
        }
    }

    @Override
    public void onInstallReferrerServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
});

دریافت ارجاع‌دهنده نصب

پس‌از برقراری اتصال به برنامه «فروشگاه Play»، با تکمیل مراحل زیر، جزئیات را از ارجاع‌دهنده نصب دریافت کنید:

1. از روش همگام‌سازی‌شده getInstallReferrer() برای برگرداندن نمونه‌ای از ReferrerDetails استفاده کنید.

2. از روش‌هایی که کلاس ReferrerDetails ارائه می‌دهد برای دریافت جزئیات درباره ارجاع‌دهنده نصب استفاده کنید.

کد زیر نشان می‌دهد که چگونه می‌توانید به اطلاعات ارجاع‌دهنده نصب دسترسی پیدا کنید:

کاتلین

val response: ReferrerDetails = referrerClient.installReferrer
val referrerUrl: String = response.installReferrer
val referrerClickTime: Long = response.referrerClickTimestampSeconds
val appInstallTime: Long = response.installBeginTimestampSeconds
val instantExperienceLaunched: Boolean = response.googlePlayInstantParam

جاوا

ReferrerDetails response = referrerClient.getInstallReferrer();
String referrerUrl = response.getInstallReferrer();
long referrerClickTime = response.getReferrerClickTimestampSeconds();
long appInstallTime = response.getInstallBeginTimestampSeconds();
boolean instantExperienceLaunched = response.getGooglePlayInstantParam();

احتیاط: اطلاعات ارجاع‌دهنده نصب به‌مدت ۹۰ روز دردسترس خواهد بود و تغییر نخواهد کرد مگراینکه برنامه دوباره نصب شود. برای جلوگیری از فراخوانی‌های غیرضروری میانای برنامه‌سازی کاربردی در برنامه‌تان، باید میانای برنامه‌سازی کاربردی را فقط یک‌بار درطول اولین اجرا پس‌از نصب فراخوانی کنید.

درحال بستن اتصال سرویس

پس‌از دریافت اطلاعات ارجاع‌دهنده، روش endConnection() را در نمونه InstallReferrerClient فراخوانی کنید تا اتصال بسته شود. بستن اتصال به شما کمک می‌کند از نشت و مشکلات عملکرد جلوگیری کنید.

برای اطلاعات بیشتر، به مرجع کتابخانه ارجاع‌دهنده نصب Play مراجعه کنید.