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

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

يتناول هذا الدليل أساسيات استرداد معلومات الإحالة من Google Play باستخدام مكتبة مُحيل التثبيت في Play.

ملاحظة: إذا كنت تطوّر تطبيقك باستخدام لغة أخرى غير لغة برمجة Kotlin أو لغة برمجة Java، يمكنك التفاعل مباشرةً مع ملف AIDL باستخدام واجهة برمجة التطبيقات لمحيل التثبيت في Play.

تحديث العناصر الاعتمادية لتطبيقك

أضِف السطر التالي إلى قسم التبعيات في ملف 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 Library، يجب إنشاء اتصال بتطبيق "متجر Play" باستخدام الخطوات التالية:

1. استدعِ الطريقة newBuilder() لإنشاء مثيل من InstallReferrerClient class.

2. يمكنك استدعاء startConnection() لربط حسابك بـ Google Play.

3. إنّ طريقة startConnection() غير متزامنة، لذا يجب إلغاء الأمر InstallReferrerStateListener لتلقّي معاودة اتصال بعد اكتمال startConnection().

4. يمكنك إلغاء طريقة onInstallReferrerSetupFinished() ليتم إعلامك عند اكتمال معاودة الاتصال. يتم استدعاء هذه الطريقة برمز استجابة يجب عليك استخدامه للتعامل مع الحالات المختلفة. يشير الرمز OK إلى أن الاتصال كان ناجحًا. تشير كل ثوان InstallReferrerResponse الأخرى إلى أنواع مختلفة من الأخطاء.

5. يمكنك إلغاء طريقة onInstallReferrerServiceDisconnected() للتعامل مع الاتصالات المفقودة إلى Google Play. على سبيل المثال، قد يفقد برنامج "مكتبة مُحيل التثبيت من Play" الاتصال في حال تحديث خدمة "متجر Play" في الخلفية. يجب أن يستدعي برنامج المكتبة الطريقة startConnection() لإعادة تشغيل الاتصال قبل إجراء المزيد من الطلبات.

يوضح الرمز التالي كيفية بدء واختبار الاتصال بتطبيق "متجر 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.
    }
});

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

بعد الربط بتطبيق "متجر 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();

تحذير: ستظل معلومات مُحيل التثبيت متاحة لمدة 90 يومًا ولن تتغير ما لم تتم إعادة تثبيت التطبيق. لتجنُّب طلبات البيانات غير الضرورية من واجهة برمجة التطبيقات في تطبيقك، يجب استدعاء واجهة برمجة التطبيقات مرة واحدة فقط أثناء عملية التنفيذ الأولى بعد التثبيت.

إغلاق اتصال الخدمة

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

للمزيد من المعلومات، يُرجى الرجوع إلى مرجع مكتبة مُحيل التثبيت في Play.