دمج المراجعات داخل التطبيق (Kotlin أو Java)

يوضّح هذا الدليل كيفية دمج المراجعات داخل التطبيق باستخدام برمجة Kotlin أو Java. تتوفّر أدلة دمج منفصلة إذا كنت تستخدم رمزًا برمجيًا أصليًا أو Unity أو Unreal Engine.

إعداد بيئة التطوير

"مكتبة المراجعات داخل التطبيقات" في Play هي جزء من مكتبات Google Play الأساسية. أدرِج التبعية التالية لـ Gradle لدمج مكتبة "المراجعة داخل التطبيق" من Play.

رائع

// In your app's build.gradle file:
...
dependencies {
    // This dependency is downloaded from the Google's Maven repository.
    // So, make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.play:review:2.0.2'

    // For Kotlin users also add the Kotlin extensions library for Play In-App Review:
    implementation 'com.google.android.play:review-ktx:2.0.2'
    ...
}

Kotlin

// In your app's build.gradle.kts file:
...
dependencies {
    // This dependency is downloaded from the Google's Maven repository.
    // So, make sure you also include that repository in your project's build.gradle file.
    implementation("com.google.android.play:review:2.0.2")

    // For Kotlin users also import the Kotlin extensions library for Play In-App Review:
    implementation("com.google.android.play:review-ktx:2.0.2")
    ...
}

إنشاء ReviewManager

ReviewManager هي الواجهة التي تتيح لتطبيقك بدء عملية مراجعة داخل التطبيق. يمكنك الحصول عليه من خلال إنشاء مثيل باستخدام علامة إشاره ReviewManagerFactory.

Kotlin

val manager = ReviewManagerFactory.create(context)

Java

ReviewManager manager = ReviewManagerFactory.create(context)

طلب عنصر ReviewInfo

اتّبِع الإرشادات حول حالات طلب المراجعات داخل التطبيق لتحديد نقاط جيدة في مسار المستخدِم في تطبيقك لطلب مراجعة منه (على سبيل المثال، عندما يُكمل المستخدِم مستوى في لعبة). عندما يصل تطبيقك إلى إحدى هذه النقاط، استخدِم مثيل ReviewManager لإنشاء مهمة طلب. في حال نجاح العملية، تعرض واجهة برمجة التطبيقات عنصر ReviewInfo المطلوب لبدء عملية المراجعة داخل التطبيق.

Kotlin

val request = manager.requestReviewFlow()
request.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // We got the ReviewInfo object
        val reviewInfo = task.result
    } else {
        // There was some problem, log or handle the error code.
        @ReviewErrorCode val reviewErrorCode = (task.getException() as ReviewException).errorCode
    }
}

Java

ReviewManager manager = ReviewManagerFactory.create(this);
Task<ReviewInfo> request = manager.requestReviewFlow();
request.addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        // We can get the ReviewInfo object
        ReviewInfo reviewInfo = task.getResult();
    } else {
        // There was some problem, log or handle the error code.
        @ReviewErrorCode int reviewErrorCode = ((ReviewException) task.getException()).getErrorCode();
    }
});

ملاحظة: لا يكون عنصر ReviewInfo صالحًا إلا لفترة محدودة. يجب أن يطلب تطبيقك عنصر ReviewInfo مسبقًا (التخزين المؤقت المُسبَق)، ولكن فقط بعد التأكّد من أنّ تطبيقك سيطلق عملية المراجعة داخل التطبيق.

بدء عملية المراجعة داخل التطبيق

استخدِم مثيل ReviewInfo لبدء مسار المراجعة داخل التطبيق. انتظِر إلى أن يُكمل المستخدم مسار المراجعة داخل التطبيق قبل أن يواصل تطبيقك مسار المستخدم العادي (مثل الانتقال إلى المستوى التالي).

Kotlin

val flow = manager.launchReviewFlow(activity, reviewInfo)
flow.addOnCompleteListener { _ ->
    // The flow has finished. The API does not indicate whether the user
    // reviewed or not, or even whether the review dialog was shown. Thus, no
    // matter the result, we continue our app flow.
}

Java

Task<Void> flow = manager.launchReviewFlow(activity, reviewInfo);
flow.addOnCompleteListener(task -> {
    // The flow has finished. The API does not indicate whether the user
    // reviewed or not, or even whether the review dialog was shown. Thus, no
    // matter the result, we continue our app flow.
});

ملاحظة مهمة: في حال حدوث خطأ أثناء عملية المراجعة داخل التطبيق، لا تُعلِم العميل بذلك ولا تغيِّر مسار المستخدم العادي في تطبيقك. واصِل مسار المستخدِم المعتاد في تطبيقك بعد استدعاء onComplete.

الخطوات التالية

اختبِر مسار المراجعة داخل تطبيقك للتأكّد من أنّ عملية الدمج تعمل بشكلٍ سليم.