ผสานรวมรีวิวในแอป (เนทีฟ)

คู่มือนี้อธิบายวิธีผสานรวมการรีวิวในแอปในแอปของคุณโดยใช้โค้ดเนทีฟ (C หรือ C++) เรามีคู่มือการผสานรวมแยกต่างหากให้หากคุณใช้ Kotlin หรือ Java, Unity หรือ Unreal Engine

ภาพรวมของ Native SDK

Play Core Native SDK เป็นส่วนหนึ่งของตระกูลไลบรารี Google Play Core Play Core Native SDK มีไฟล์ส่วนหัว C ชื่อ review.h ซึ่งครอบคลุม ReviewManager จากไลบรารีการรีวิวในแอปของ Java Play ไฟล์ส่วนหัวนี้ช่วยให้แอปของคุณเรียกใช้ API ได้โดยตรงจากโค้ดแบบเนทีฟ หากต้องการดูภาพรวมของฟังก์ชันสาธารณะที่พร้อมใช้งาน โปรดดูเอกสารประกอบของโมดูลเนทีฟการรีวิวใน Play

ReviewManager_requestReviewFlow จะเริ่มคำขอที่รวบรวมข้อมูลที่จำเป็นสำหรับการเปิดตัวขั้นตอนการรีวิวในแอปในภายหลัง คุณสามารถ ติดตามผลลัพธ์ของคำขอได้โดยใช้ ReviewManager_getReviewStatus. ดูข้อมูลเพิ่มเติมเกี่ยวกับสถานะทั้งหมดที่ ReviewManager_getReviewStatus สามารถแสดงได้ที่ ReviewErrorCode

ทั้งฟังก์ชันคำขอและฟังก์ชันเปิดตัวจะแสดง REVIEW_NO_ERROR หากฟังก์ชันทำงานสำเร็จ

ตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์

1. เลือกดำเนินการอย่างหนึ่งดังต่อไปนี้

   • ติดตั้ง Android Studio เวอร์ชัน 4.0 ขึ้นไป ใช้ UI ของเครื่องมือจัดการ SDK เพื่อติดตั้ง Android SDK Platform เวอร์ชัน 10.0 (ระดับ API 29)
   • ติดตั้งเครื่องมือบรรทัดคำสั่ง Android SDK แล้วใช้ sdkmanager เพื่อติดตั้ง Android SDK Platform เวอร์ชัน 10.0 (ระดับ API 29)

2. เตรียม Android Studio สำหรับการพัฒนาเนทีฟโดยใช้ เครื่องมือจัดการ SDK เพื่อติดตั้ง CMake และ Android Native Development Kit (NDK) เวอร์ชันล่าสุด ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างหรือนำเข้าโปรเจ็กต์เนทีฟได้ที่ หัวข้อ เริ่มต้นใช้งาน NDK

3. ดาวน์โหลดไฟล์ zip แล้วแตกไฟล์ไว้ข้างโปรเจ็กต์

   ลิงก์ดาวน์โหลด	ขนาด	การตรวจสอบข้อผิดพลาดด้วย SHA-256
   play-core-native-sdk-1.16.0.zip	54.8 MiB	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

4. อัปเดตไฟล์ build.gradle ของแอปดังที่แสดงด้านล่าง

   ดึงดูด

       // 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.6.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.6.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. อัปเดตไฟล์ CMakeLists.txt ของแอปดังที่แสดงด้านล่าง

   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
           ...)
   

การรวบรวมข้อมูล

Play Core Native SDK อาจรวบรวมข้อมูลที่เกี่ยวข้องกับเวอร์ชันเพื่อให้ Google ปรับปรุงผลิตภัณฑ์ ซึ่งรวมถึงข้อมูลต่อไปนี้

• ชื่อแพ็กเกจของแอป
• เวอร์ชันแพ็กเกจของแอป
• เวอร์ชันของ Play Core Native SDK

ระบบจะรวบรวมข้อมูลนี้เมื่อคุณอัปโหลดแพ็กเกจแอป ไปยัง Play Console หากต้องการไม่เข้าร่วมกระบวนการเก็บรวบรวมข้อมูลนี้ ให้นำ $playcoreDir/playcore-native-metadata.jar ออกจากการนำเข้าในไฟล์ build.gradle

โปรดทราบว่าการเก็บรวบรวมข้อมูลนี้เกี่ยวข้องกับการใช้ Play Core Native SDK ของคุณ และการใช้ข้อมูลที่เก็บรวบรวมของ Google นั้นแยกจากและไม่ขึ้นอยู่กับการรวบรวมทรัพยากร Dependency ของไลบรารีที่ประกาศไว้ใน Gradle เมื่อคุณอัปโหลดแพ็กเกจแอปไปยัง Play Console

หลังจากผสานรวม Play Core Native SDK เข้ากับโปรเจ็กต์แล้ว ให้ใส่บรรทัดต่อไปนี้ในไฟล์ที่มีการเรียก API

ใส่ review.h

หลังจากผสานรวม Play Core Native SDK เข้ากับโปรเจ็กต์แล้ว ให้ใส่บรรทัดต่อไปนี้ในไฟล์ที่จะมีการเรียก API

#include "play/review.h"

เริ่มต้น API การรีวิว

เมื่อใดก็ตามที่คุณต้องการใช้ API คุณต้องเริ่มต้น API ก่อนโดยเรียกใช้ฟังก์ชัน ReviewManager_init ดังที่แสดงในตัวอย่างต่อไปนี้ที่สร้าง ด้วย android_native_app_glue.h:

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.
  }
}

ขอขั้นตอนการรีวิวในแอป

ทำตามคำแนะนำเกี่ยวกับ เวลาที่ควรขอการรีวิวในแอป เพื่อกำหนดจุดที่เหมาะสม ในขั้นตอนของผู้ใช้ในแอปเพื่อแสดงข้อความเตือนให้ผู้ใช้เขียนรีวิว (เช่น หลังจากที่ผู้ใช้ปิดหน้าจอสรุปเมื่อจบระดับในเกม) เมื่อ แอปของคุณใกล้ถึงจุดใดจุดหนึ่งเหล่านี้ ให้เรียกใช้ ReviewManager_requestReviewFlow เพื่อขอข้อมูล ที่แอปของคุณต้องใช้ในการเปิดตัวขั้นตอนการรีวิวในแอปแบบไม่พร้อมกัน ตรวจสอบความคืบหน้าของการดำเนินการ ReviewManager_requestReviewFlow โดยเรียกใช้ ReviewManager_getReviewStatus เช่น ทุกเฟรม กระบวนการนี้อาจใช้เวลาไม่กี่วินาที ดังนั้นคุณควรเริ่มกระบวนการนี้ก่อนที่แอปจะถึงจุดที่คุณต้องการแสดงขั้นตอนการรีวิวในแอป

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.
}

จัดการสถานะและเปิดตัวขั้นตอนการรีวิวในแอป

เมื่อใดก็ตามที่คำขอเริ่มต้นขึ้นหรือมีการเปิดตัวขั้นตอนการรีวิวในแอป คุณสามารถ ตรวจสอบสถานะได้โดยใช้ ReviewManager_getReviewStatus ซึ่งจะช่วยให้คุณกำหนดตรรกะได้ตามสถานะ API วิธีหนึ่งในการดำเนินการนี้คือเก็บสถานะไว้เป็นตัวแปรร่วมและตรวจสอบว่าสถานะเป็น REVIEW_REQUEST_FLOW_COMPLETED หรือไม่เมื่อผู้ใช้ดำเนินการบางอย่าง (เช่น แตะปุ่ม "ระดับถัดไป" ในเกม) ดังที่แสดงในตัวอย่างต่อไปนี้

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;
}

เมื่อสถานะเป็น REVIEW_REQUEST_FLOW_COMPLETED และแอปของคุณพร้อมแล้ว ให้เปิดตัวขั้นตอนการรีวิวในแอป

// 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;
}

หลังจากเปิดตัวขั้นตอนการรีวิวในแอปแล้ว ให้ตรวจสอบสถานะต่อไปจนกว่าจะเสร็จสมบูรณ์ แล้วดำเนินการตามขั้นตอนของแอปต่อไป วิธีทั่วไปในการจัดการเรื่องนี้คือทำตามรูปแบบ Game Loop

ปล่อยทรัพยากร

อย่าลืมปล่อยทรัพยากรโดยเรียกใช้ReviewManager_destroy ฟังก์ชันเมื่อแอปของคุณใช้ API เสร็จแล้ว (เช่น หลังจากขั้นตอนการรีวิวในแอป เสร็จสมบูรณ์)

void ReviewManager_destroy();

ขั้นตอนถัดไป

ทดสอบขั้นตอนการรีวิวในแอปของแอป เพื่อยืนยันว่าการผสานรวมทำงาน อย่างถูกต้อง