مكتبة المُحيل في متجر Play
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يمكنك استخدام واجهة Install Referrer API في "متجر Google Play" لاسترداد
محتوى الإحالة من Google Play مكتبة عملاء Play Install Referrer API
بلغة برمجة Java وهو برنامج تضمين لنظام التشغيل Android
ملف لغة تعريف الواجهة (AIDL) الذي يحدد واجهة
تثبيت خدمة المُحيل. يمكنك استخدام برنامج Play Install Referrer API
مكتبة لتبسيط عملية التطوير.
يتناول هذا الدليل أساسيات استرداد معلومات الإحالة من Google.
يمكنك اللعب باستخدام مكتبة مُحيل التثبيت على Play.
تعديل اعتماديات تطبيقك
أضِف السطر التالي إلى قسم الموارد التابعة في ملف build.gradle
.
عن تطبيقك:
Groovy
dependencies {
...
implementation "com.android.installreferrer:installreferrer:2.2"
}
Kotlin
dependencies {
...
implementation("com.android.installreferrer:installreferrer:2.2")
}
جارٍ الاتصال بـ Google Play
قبل أن تتمكّن من استخدام مكتبة واجهة برمجة التطبيقات Play Install Referrer API، عليك
عليك الربط بتطبيق "متجر Play" باستخدام ما يلي:
الخطوات:
- عليك استدعاء
newBuilder()
لإنشاء مثيل
InstallReferrerClient
الصف.
عليك استدعاء
startConnection()
لإنشاء اتصال بـ Google Play.
startConnection()
غير متزامن، لذا يجب تجاوز
InstallReferrerStateListener
لتلقي معاودة الاتصال بعد
startConnection()
تكتمل.
إلغاء onInstallReferrerSetupFinished()
إرسال إشعار عند اكتمال معاودة الاتصال. تُسمى هذه الطريقة
برمز استجابة يجب استخدامه للتعامل مع الحالات المختلفة.
OK
إلى أن الاتصال كان ناجحًا. كل من الآخر
InstallReferrerResponse
تشير الثوابت إلى أنواع مختلفة من الأخطاء.
إلغاء onInstallReferrerServiceDisconnected()
للتعامل مع الاتصالات المفقودة مع Google Play. بالنسبة
مثلاً، قد يفقد برنامج "Play Install Referrer Library" (مكتبة المُحيلة) من 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.
المرجع:
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Play Install Referrer Library\n\nYou can use the Google Play Store's Install Referrer API to securely retrieve\nreferral content from Google Play. The Play Install Referrer API Client Library\nis written in the Java programming language and is a wrapper for the Android\nInterface Definition Language (AIDL) file that defines the interface to the\nInstall Referrer service. You can use the Play Install Referrer API Client\nLibrary to simplify your development process.\n\nThis guide covers the basics of retrieving referral information from Google\nPlay using the Play Install Referrer Library.\n| **Note:** If you are developing your app using a language other than the Kotlin programming language or the Java programming language, you can interact directly with the AIDL file by using the [Play Install Referrer\n| API](/google/play/installreferrer/igetinstallreferrerservice).\n\nUpdating your app's dependencies\n--------------------------------\n\nAdd the following line to the dependencies section of the `build.gradle` file\nfor your app: \n\n### Groovy\n\n```groovy\ndependencies {\n ...\n implementation \"com.android.installreferrer:installreferrer:2.2\"\n}\n```\n\n### Kotlin\n\n```kotlin\ndependencies {\n ...\n implementation(\"com.android.installreferrer:installreferrer:2.2\")\n}\n```\n\nConnecting to Google Play\n-------------------------\n\nBefore you can use the Play Install Referrer API Library, you must\nestablish a connection to the Play Store app using the following\nsteps:\n\n1. Call the [`newBuilder()`](/reference/com/android/installreferrer/api/InstallReferrerClient#newBuilder(android.content.Context)) method to create an instance of [`InstallReferrerClient`](/reference/com/android/installreferrer/api/InstallReferrerClient) class.\n2. Call the\n [`startConnection()`](/reference/com/android/installreferrer/api/InstallReferrerClient#startConnection(com.android.installreferrer.api.InstallReferrerStateListener))\n to establish a connection to Google Play.\n\n3. The [`startConnection()`](/reference/com/android/installreferrer/api/InstallReferrerClient#startConnection(com.android.installreferrer.api.InstallReferrerStateListener))\n method is asynchronous, so you must override\n [`InstallReferrerStateListener`](/reference/com/android/installreferrer/api/InstallReferrerStateListener)\n to receive a callback after\n [`startConnection()`](/reference/com/android/installreferrer/api/InstallReferrerClient#startConnection(com.android.installreferrer.api.InstallReferrerStateListener))\n completes.\n\n4. Override the [`onInstallReferrerSetupFinished()`](/reference/com/android/installreferrer/api/InstallReferrerStateListener#onInstallReferrerSetupFinished(int))\n method to be notified when the callback completes. This method is called\n with a response code that you must use to handle the different states.\n [`OK`](https://developer.android.com/reference/com/android/installreferrer/api/InstallReferrerClient.InstallReferrerResponse#OK)\n indicates that the connection was successful. Each of the other\n [`InstallReferrerResponse`](/reference/com/android/installreferrer/api/InstallReferrerClient.InstallReferrerResponse)\n constants are for different types of errors.\n\n5. Override the [`onInstallReferrerServiceDisconnected()`](/reference/com/android/installreferrer/api/InstallReferrerStateListener#oninstallreferrerservicedisconnected)\n method to handle lost connections to Google Play. For\n example, the Play Install Referrer Library client may lose the connection if the\n Play Store service is updating in the background. The library client must call\n the\n [`startConnection()`](/reference/com/android/installreferrer/api/InstallReferrerClient#startConnection(com.android.installreferrer.api.InstallReferrerStateListener))\n method to restart the connection before making further requests.\n\nThe following code demonstrates how to start and test a connection to the\nPlay Store app: \n\n### Kotlin\n\n```kotlin\nprivate lateinit var referrerClient: InstallReferrerClient\n\nreferrerClient = InstallReferrerClient.newBuilder(this).build()\nreferrerClient.startConnection(object : InstallReferrerStateListener {\n\n override fun onInstallReferrerSetupFinished(responseCode: Int) {\n when (responseCode) {\n InstallReferrerResponse.OK -\u003e {\n // Connection established.\n }\n InstallReferrerResponse.FEATURE_NOT_SUPPORTED -\u003e {\n // API not available on the current Play Store app.\n }\n InstallReferrerResponse.SERVICE_UNAVAILABLE -\u003e {\n // Connection couldn't be established.\n }\n }\n }\n\n override fun onInstallReferrerServiceDisconnected() {\n // Try to restart the connection on the next request to\n // Google Play by calling the startConnection() method.\n }\n})\n```\n\n### Java\n\n```java\nInstallReferrerClient referrerClient;\n\nreferrerClient = InstallReferrerClient.newBuilder(this).build();\nreferrerClient.startConnection(new InstallReferrerStateListener() {\n @Override\n public void onInstallReferrerSetupFinished(int responseCode) {\n switch (responseCode) {\n case InstallReferrerResponse.OK:\n // Connection established.\n break;\n case InstallReferrerResponse.FEATURE_NOT_SUPPORTED:\n // API not available on the current Play Store app.\n break;\n case InstallReferrerResponse.SERVICE_UNAVAILABLE:\n // Connection couldn't be established.\n break;\n }\n }\n\n @Override\n public void onInstallReferrerServiceDisconnected() {\n // Try to restart the connection on the next request to\n // Google Play by calling the startConnection() method.\n }\n});\n```\n\nGetting the install referrer\n----------------------------\n\nAfter you have established a connection to the Play Store app, get the details\nfrom the install referrer by completing the following steps:\n\n1. Use the synchronized\n [`getInstallReferrer()`](/reference/com/android/installreferrer/api/InstallReferrerClient#getInstallReferrer())\n method to return an instance of\n [`ReferrerDetails`](/reference/com/android/installreferrer/api/ReferrerDetails).\n\n2. Use the methods that the\n [`ReferrerDetails`](/reference/com/android/installreferrer/api/ReferrerDetails)\n class provides to get details about the install referrer.\n\nThe following code demonstrates how you can access the install referrer\ninformation: \n\n### Kotlin\n\n```kotlin\nval response: ReferrerDetails = referrerClient.installReferrer\nval referrerUrl: String = response.installReferrer\nval referrerClickTime: Long = response.referrerClickTimestampSeconds\nval appInstallTime: Long = response.installBeginTimestampSeconds\nval instantExperienceLaunched: Boolean = response.googlePlayInstantParam\n```\n\n### Java\n\n```java\nReferrerDetails response = referrerClient.getInstallReferrer();\nString referrerUrl = response.getInstallReferrer();\nlong referrerClickTime = response.getReferrerClickTimestampSeconds();\nlong appInstallTime = response.getInstallBeginTimestampSeconds();\nboolean instantExperienceLaunched = response.getGooglePlayInstantParam();\n```\n\n**Caution:** The install referrer information will be\navailable for 90 days and **won't change** unless the application is\nreinstalled. To avoid unnecessary API calls in your app, you should invoke the\nAPI **only once** during the first execution after install.\n\nClosing service connection\n--------------------------\n\nAfter getting referrer information, call the\n[`endConnection()`](/reference/com/android/installreferrer/api/InstallReferrerClient#endConnection())\nmethod on your\n[`InstallReferrerClient`](/reference/com/android/installreferrer/api/InstallReferrerClient)\ninstance to close the connection. Closing the connection will help you avoid\nleaks and performance problems.\n\nFor further information, refer to the [Play Install Referrer Library\nReference](/reference/com/android/installreferrer/packages)."]]