Uygulama içi yorumları entegre edin (Yerel)

Bu kılavuzda, yerel (C veya C++) kodu kullanarak uygulama içi yorumları uygulamanıza nasıl entegre edeceğiniz açıklanmaktadır. Kotlin veya Java, Unity ya da Unreal Engine kullanıyorsanız ayrı entegrasyon kılavuzları vardır.

Native SDK'ya genel bakış

Play Core Native SDK, Google Play Core kitaplıkları ailesinin bir parçasıdır. Play Core Yerel SDK'sı, Java Play uygulama içi yorum kitaplıklarındaki ReviewManager öğesini sarmalayan bir C başlık dosyası (review.h) içerir. Bu başlık dosyası, uygulamanızın API'yi doğrudan yerel kodunuzdan çağırmasına olanak tanır. Kullanılabilen herkese açık işlevlere genel bakış için Play Yorumları yerel modül dokümanlarına bakın.

ReviewManager_requestReviewFlow, daha sonra uygulama içi yorum akışını başlatmak için gereken bilgileri toplayan bir istek başlatır. ReviewManager_getReviewStatus kullanarak isteğin sonucunu takip edebilirsiniz. ReviewManager_getReviewStatus tarafından döndürülebilen tüm durumlar hakkında daha fazla bilgi için ReviewErrorCode bölümüne bakın.

İşlev başarılı olursa hem istek hem de başlatma işlevleri REVIEW_NO_ERROR değerini döndürür.

Geliştirme ortamınızı kurma

1. Aşağıdakilerden birini yapın:

   • Android Studio 4.0 veya sonraki bir sürümünü yükleyin. Android SDK Platform 10.0 sürümünü (API düzeyi 29) yüklemek için SDK Yöneticisi kullanıcı arayüzünü kullanın.
   • Android SDK komut satırı araçlarını yükleyin ve sdkmanager komutunu kullanarak Android SDK Platform 10.0 sürümünü (API düzeyi 29) yükleyin.

2. En yeni CMake ve Android Native Development Kit'i (NDK) yüklemek için SDK Manager'ı kullanarak Android Studio'yu yerel geliştirmeye hazırlayın. Yerel projeler oluşturma veya içe aktarma hakkında daha fazla bilgi için NDK'yı kullanmaya başlama başlıklı makaleyi inceleyin.

3. ZIP dosyasını indirip projenizin yanına çıkarın.

   İndirme Bağlantısı	Boyut	SHA-256 Sağlaması
   play-core-native-sdk-1.15.3.zip	37,8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. Uygulamanızın build.gradle dosyasını aşağıda gösterildiği gibi güncelleyin:

   Groovy

       // App build.gradle
   
       plugins {
         id 'com.android.application'
       }
   
       // Define a path to the extracted Play Core SDK files.
       // If using a relative path, wrap it with file() since CMake requires absolute paths.
       def playcoreDir = file('../path/to/playcore-native-sdk')
   
       android {
           defaultConfig {
               ...
               externalNativeBuild {
                   cmake {
                       // Define the PLAYCORE_LOCATION directive.
                       arguments "-DANDROID_STL=c++_static",
                                 "-DPLAYCORE_LOCATION=$playcoreDir"
                   }
               }
               ndk {
                   // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
                   abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
               }
           }
           buildTypes {
               release {
                   // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
                   proguardFile '$playcoreDir/proguard/common.pgcfg'
                   proguardFile '$playcoreDir/proguard/gms_task.pgcfg'
                   proguardFile '$playcoreDir/proguard/per-feature-proguard-files'
                   ...
               }
               debug {
                   ...
               }
           }
           externalNativeBuild {
               cmake {
                   path 'src/main/CMakeLists.txt'
               }
           }
       }
   
       dependencies {
           // Import these feature-specific AARs for each Google Play Core library.
           implementation 'com.google.android.play:app-update:2.1.0'
           implementation 'com.google.android.play:asset-delivery:2.3.0'
           implementation 'com.google.android.play:integrity:1.4.0'
           implementation 'com.google.android.play:review:2.0.2'
   
           // Import these common dependencies.
           implementation 'com.google.android.gms:play-services-tasks:18.0.2'
           implementation files("$playcoreDir/playcore-native-metadata.jar")
           ...
       }
       

   Kotlin

   // App build.gradle
   
   plugins {
       id("com.android.application")
   }
   
   // Define a path to the extracted Play Core SDK files.
   // If using a relative path, wrap it with file() since CMake requires absolute paths.
   val playcoreDir = file("../path/to/playcore-native-sdk")
   
   android {
       defaultConfig {
           ...
           externalNativeBuild {
               cmake {
                   // Define the PLAYCORE_LOCATION directive.
                   arguments += listOf("-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir")
               }
           }
           ndk {
               // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
               abiFilters.clear()
               abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
           }
       }
       buildTypes {
           release {
               // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
               proguardFile("$playcoreDir/proguard/common.pgcfg")
               proguardFile("$playcoreDir/proguard/gms_task.pgcfg")
               proguardFile("$playcoreDir/proguard/per-feature-proguard-files")
               ...
           }
           debug {
               ...
           }
       }
       externalNativeBuild {
           cmake {
               path = "src/main/CMakeLists.txt"
           }
       }
   }
   
   dependencies {
       // Import these feature-specific AARs for each Google Play Core library.
       implementation("com.google.android.play:app-update:2.1.0")
       implementation("com.google.android.play:asset-delivery:2.3.0")
       implementation("com.google.android.play:integrity:1.4.0")
       implementation("com.google.android.play:review:2.0.2")
   
       // Import these common dependencies.
       implementation("com.google.android.gms:play-services-tasks:18.0.2")
       implementation(files("$playcoreDir/playcore-native-metadata.jar"))
       ...
   }

5. Uygulamanızın CMakeLists.txt dosyalarını aşağıda gösterildiği gibi güncelleyin:

   cmake_minimum_required(VERSION 3.6)
   
   ...
   
   # Add a static library called “playcore” built with the c++_static STL.
   include(${PLAYCORE_LOCATION}/playcore.cmake)
   add_playcore_static_library()
   
   // In this example “main” is your native code library, i.e. libmain.so.
   add_library(main SHARED
           ...)
   
   target_include_directories(main PRIVATE
           ${PLAYCORE_LOCATION}/include
           ...)
   
   target_link_libraries(main
           android
           playcore
           ...)
   

Veri Toplama

Play Core Yerel SDK'sı, Google'ın ürünü iyileştirmesine olanak tanımak için sürümle ilgili veriler toplayabilir. Örneğin:

• Uygulamanın paket adı
• Uygulamanın paket sürümü
• Play Core Yerel SDK'sının sürümü

Bu veriler, Play Console'a uygulama paketinizi yüklediğinizde toplanır. Bu veri toplama sürecini devre dışı bırakmak için build.gradle dosyasındaki $playcoreDir/playcore-native-metadata.jar içe aktarma işlemini kaldırın.

Play Core Native SDK kullanımınızla ilgili bu veri toplama işleminin ve Google'ın toplanan verileri kullanımının, uygulama paketinizi Play Console'a yüklediğinizde Gradle'da beyan edilen kitaplık bağımlılıklarının Google tarafından toplanmasından ayrı ve bağımsız olduğunu unutmayın.

Play Core Native SDK'yı projenize entegre ettikten sonra API çağrıları içeren dosyalara aşağıdaki satırı ekleyin:

review.h dosyasını ekleyin.

Play Core Yerel SDK'sını projenize entegre ettikten sonra API çağrılarını içerecek dosyalara aşağıdaki satırı ekleyin:

#include "play/review.h"

Review API'yi başlatma

API'yi her kullanmak istediğinizde, ReviewManager_init işlevini çağırarak önce başlatmanız gerekir. Bu işlev, android_native_app_glue.h ile oluşturulan aşağıdaki örnekte gösterilmiştir:

void android_main(android_app* app) {
  app->onInputEvent = HandleInputEvent;

  ReviewErrorCode error_code = ReviewManager_init(app->activity->vm, app->activity->clazz);
  if (error_code == REVIEW_NO_ERROR) {
    // You can use the API.
  }
}

Uygulama içi yorum akışını isteme

Kullanıcıdan yorum istemek için uygulamanızın kullanıcı akışında uygun noktaları belirlemek üzere uygulama içi yorumları ne zaman isteyeceğinizle ilgili yönergeleri uygulayın (ör. kullanıcı bir oyunda seviyenin sonundaki özet ekranını kapattıktan sonra). Uygulamanız bu noktalardan birine yaklaştığında, uygulama içi yorum akışını başlatmak için ihtiyaç duyduğu bilgileri eşzamansız olarak istemek üzere ReviewManager_requestReviewFlow işlevini çağırın. Örneğin, her karede bir kez ReviewManager_getReviewStatus çağırarak ReviewManager_requestReviewFlow işleminin ilerleme durumunu izleyin. Bu işlem birkaç saniye sürebilir. Bu nedenle, uygulamanızda uygulama içi yorum akışını göstermek istediğiniz noktaya ulaşmadan önce bu süreci başlatmanız gerekir.

ReviewErrorCode error_code = ReviewManager_requestReviewFlow();
if (error_code == REVIEW_NO_ERROR) {
    // The request has successfully started, check the status using
    // ReviewManager_getReviewStatus.
} else {
    // Error such as REVIEW_PLAY_STORE_NOT_FOUND indicating that the in-app
    // review isn't currently possible.
}

İşleme durumlarını yönetme ve uygulama içi yorum akışını başlatma

Bir istek başlatıldığında veya uygulama içi inceleme akışı başlatıldığında ReviewManager_getReviewStatus simgesini kullanarak durumu kontrol edebilirsiniz. Bu sayede, API durumuna bağlı olarak mantığı tanımlayabilirsiniz. Bu soruna yaklaşmanın bir yolu, durumu genel bir değişken olarak tutmak ve kullanıcı belirli bir işlemi (örneğin, bir oyunda "Sonraki Seviye" düğmesine dokunma) gerçekleştirdiğinde durumun REVIEW_REQUEST_FLOW_COMPLETED olup olmadığını kontrol etmektir. Bu durum, aşağıdaki örnekte gösterilmiştir:

ReviewStatus status;
ReviewErrorCode error_code = ReviewManager_getReviewStatus(&status);
if (error_code != REVIEW_NO_ERROR) {
    // There was an error with the most recent operation.
    return;
}

switch (status) {
    case REVIEW_REQUEST_FLOW_PENDING:
        // Request is ongoing. The flow can't be launched yet.
        break;
    case REVIEW_REQUEST_FLOW_COMPLETED:
        // Request completed. The flow can be launched now.
        break;
    case REVIEW_LAUNCH_FLOW_PENDING:
        // The review flow is ongoing, meaning the dialog might be displayed.
        break;
    case REVIEW_LAUNCH_FLOW_COMPLETED:
        // The review flow has finished. Continue with your app flow (for
        // example, move to the next screen).
        break;
    default:
        // Unknown status.
        break;
}

Durum REVIEW_REQUEST_FLOW_COMPLETED olduğunda ve uygulamanız hazır olduğunda uygulama içi inceleme akışını başlatın:

// This call uses android_native_app_glue.h.
ReviewErrorCode error_code = ReviewManager_launchReviewFlow(app->activity->clazz);
if (error_code != REVIEW_NO_ERROR) {
    // There was an error while launching the flow.
    return;
}

Uygulama içi yorum akışını başlattıktan sonra, tamamlanma durumunu kontrol etmeye devam edin ve uygulama akışınıza devam edin. Bu durumu ele almanın yaygın bir yolu, Oyun Döngüsü modelini izlemektir.

Ücretsiz kaynaklar

Uygulamanız API'yi kullanmayı bitirdikten sonra (örneğin, uygulama içi inceleme akışı tamamlandıktan sonra) ReviewManager_destroy işlevini çağırarak kaynakları boşaltmayı unutmayın.

void ReviewManager_destroy();

Sonraki adımlar

Entegrasyonunuzun doğru şekilde çalıştığını doğrulamak için uygulamanızın uygulama içi yorum akışını test edin.