يمكنك استخدام واجهة برمجة التطبيقات Install Referrer API من "متجر Google Play" لاسترداد محتوى الإحالة من Google Play بأمان. إنّ "مكتبة برامج واجهة برمجة التطبيقات المُحيلة من Play" مكتوبة بلغة البرمجة Java وهي برنامج تضمين لملف "لغة تعريف واجهة المستخدم (AIDL)" لنظام التشغيل Android، وهو يحدِّد الواجهة في خدمة "مُحيل التثبيت". يمكنك استخدام مكتبة برامج واجهة برمجة التطبيقات المُحيلة من Play لتبسيط عملية التطوير.
يتناول هذا الدليل أساسيات استرداد معلومات الإحالة من Google Play باستخدام مكتبة مُحيل التثبيت في 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" باستخدام الخطوات التالية:
- استدعِ الطريقة
newBuilder()
لإنشاء مثيل منInstallReferrerClient
class. يمكنك استدعاء
startConnection()
لربط حسابك بـ Google Play.إنّ طريقة
startConnection()
غير متزامنة، لذا يجب إلغاء الأمرInstallReferrerStateListener
لتلقّي معاودة اتصال بعد اكتمالstartConnection()
.يمكنك إلغاء طريقة
onInstallReferrerSetupFinished()
ليتم إعلامك عند اكتمال معاودة الاتصال. يتم استدعاء هذه الطريقة برمز استجابة يجب عليك استخدامه للتعامل مع الحالات المختلفة. يشير الرمزOK
إلى أن الاتصال كان ناجحًا. تشير كل ثوانInstallReferrerResponse
الأخرى إلى أنواع مختلفة من الأخطاء.يمكنك إلغاء طريقة
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"، يمكنك الحصول على التفاصيل من مُحيل التثبيت من خلال إكمال الخطوات التالية:
استخدِم طريقة
getInstallReferrer()
المتزامنة لعرض مثيلReferrerDetails
.استخدِم الطرق التي توفّرها الفئة
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.