مكتبة المُحيل في متجر Play

يمكنك استخدام واجهة برمجة التطبيقات Install Referrer API في "متجر Google Play" لاسترداد محتوى الإحالة بأمان من Google Play. تمت كتابة مكتبة برامج Play Install Referrer API بلغة برمجة Java، وهي برنامج تضمين لملف لغة تعريف واجهة نظام Android (AIDL) الذي يحدّد واجهة خدمة Install Referrer. يمكنك استخدام مكتبة عميل Play Install Referrer API لتبسيط عملية التطوير.

يتناول هذا الدليل أساسيات استرداد معلومات الإحالة من Google Play باستخدام Play Install Referrer Library.

تعديل التبعيات في تطبيقك

أضِف السطر التالي إلى قسم التبعيات في ملف build.gradle لتطبيقك:

أنيق

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

Kotlin

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

جارٍ الاتصال بـ Google Play

قبل أن تتمكّن من استخدام مكتبة Play Install Referrer API، عليك إنشاء اتصال بتطبيق "متجر Google Play" باتّباع الخطوات التالية:

  1. استدعِ طريقة newBuilder() لإنشاء مثيل من فئة InstallReferrerClient.
  2. استدعِ طريقة startConnection() لإنشاء اتصال بـ Google Play.
  3. بما أنّ startConnection() غير متزامن، يمكنك تنفيذ InstallReferrerStateListener لتلقّي طلب معاودة الاتصال بعد اكتمال startConnection().
  4. يمكنك إلغاء طريقة onInstallReferrerSetupFinished() لتلقّي إشعار عند اكتمال ردّ الاتصال. تمرّر هذه الطريقة رمز استجابة يجب استخدامه للتعامل مع الحالات المختلفة. تشير السمة OK إلى نجاح عملية الربط. تشير ثوابت InstallReferrerResponse الأخرى إلى أنواع مختلفة من الأخطاء.
  5. يمكنك إلغاء طريقة onInstallReferrerServiceDisconnected() للتعامل مع الاتصالات المفقودة بـ Google Play. على سبيل المثال، قد ينقطع اتصال عميل مكتبة Play Install Referrer إذا كانت خدمة "متجر Google Play" قيد التحديث في الخلفية. يجب أن يستدعي عميل المكتبة طريقة startConnection() لإعادة تشغيل الاتصال قبل تقديم طلبات أخرى.

يوضّح الرمز التالي كيفية بدء الاتصال بتطبيق "متجر Google Play" واختباره:

Kotlin

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

Java

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.
    }
});

الحصول على مُحيل التثبيت

بعد إنشاء اتصال بتطبيق "متجر Google Play"، يمكنك الحصول على التفاصيل من مصدر الإحالة الناجحة للتثبيت من خلال إكمال الخطوات التالية:

  1. استخدِم طريقة getInstallReferrer() المتزامنة لعرض مثيل من ReferrerDetails.
  2. استخدِم الطرق التي توفّرها فئة ReferrerDetails للحصول على تفاصيل حول مُحيل التثبيت.

يوضّح الرمز التالي كيفية الوصول إلى معلومات مُحيل التثبيت:

Kotlin

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

Java

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

جارٍ إغلاق اتصال الخدمة

بعد الحصول على معلومات المُحيل، يمكنك استدعاء طريقة endConnection() في مثيل InstallReferrerClient لإغلاق الاتصال. يساعدك إغلاق الاتصال في تجنُّب تسرُّب البيانات ومشاكل الأداء.

لمزيد من المعلومات، يُرجى الرجوع إلى مرجع Play Install Referrer Library.