Mengintegrasikan pencapaian

Dokumen ini menjelaskan cara mengintegrasikan pencapaian ke dalam game menggunakan Konsol Google Play atau panggilan API. Dokumen ini mencakup elemen dan status penting pencapaian, serta menjelaskan cara membuat, mengimpor, dan mengelolanya.

Sebelum memulai

Membuat atau mengimpor pencapaian baru

Untuk menerapkan pencapaian dari awal, ikuti langkah-langkah berikut:

Tambahkan pencapaian

Anda dapat membuat pencapaian untuk pertama kalinya menggunakan Konsol Google Play dengan dua cara:

  • Membuat pencapaian: Tambahkan definisi dan metadata untuk setiap pencapaian satu per satu.
  • Mengimpor pencapaian: Impor definisi dan metadata lainnya untuk beberapa pencapaian secara bersamaan dalam satu langkah.

Membuat pencapaian

Untuk membuat pencapaian game baru yang tidak dipublikasikan, selesaikan langkah-langkah berikut:

  1. Di Konsol Google Play, pilih game.
  2. Di halaman Layanan game Play - Pencapaian (Mendorong pertumbuhan > Layanan game Play > Penyiapan dan pengelolaan > Pencapaian), pilih Buat pencapaian.
  3. Di halaman Tambahkan pencapaian, lengkapi formulir.
  4. Klik Simpan sebagai draf.
  5. Setelah membuat pencapaian, Anda harus memublikasikan pencapaian.
Impor pencapaian

Untuk menambahkan beberapa pencapaian ke game Anda sekaligus, gunakan langkah-langkah berikut:

  1. Buat file ZIP yang berisi pencapaian Anda.
  2. Upload file.

Untuk mengetahui informasi selengkapnya tentang file ZIP, lihat Panduan file ZIP.

Untuk mengimpor pencapaian:

  1. Di Konsol Google Play, pilih game.
  2. Di halaman Layanan game Play - Pencapaian (Mendorong pertumbuhan > Layanan game Play > Penyiapan dan pengelolaan > Pencapaian), pilih Impor pencapaian.
  3. Di halaman Impor pencapaian, klik Upload.
  4. Pilih file zip yang akan diupload.
  5. Klik Simpan sebagai draf.
  6. Setelah mengimpor pencapaian, Anda harus memublikasikan game.

Panduan file ZIP

Anda dapat mengimpor beberapa pencapaian sekaligus menggunakan file zip. Lihat tabel untuk mengetahui nama file yang tepat untuk digunakan dalam file zip Anda:

Nama file Wajib Diisi atau Opsional Nilai yang diterima
AchievementsMetadata.csv Wajib Metadata untuk setiap pencapaian. Lihat Atribut.
AchievementsLocalizations.csv Opsional Memberikan terjemahan untuk nama dan deskripsi pencapaian.
AchievementsIconMappings.csv Opsional Memetakan pencapaian ke file ikonnya.
File ikon Opsional Ikon dalam format PNG, JPEG, atau JPG.

Persyaratan file ZIP:

  • Tidak ada subdirektori.
  • Nama file yang unik.
  • Hanya file CSV, PNG, JPEG, atau JPG.
  • File CSV tidak boleh memiliki baris header.
  • Ukuran setiap file tidak boleh lebih dari 1 MB.
  • File ZIP tidak boleh berisi lebih dari 203 file.
  • Total ukuran file zip tidak boleh lebih dari 200 MB.
Format AchievementsMetadata.csv

File AchievementsMetadata.csv berisi metadata untuk setiap pencapaian. File ini harus menyertakan informasi sebagai nilai yang dipisahkan koma dalam urutan berikut:

    Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order

Kolom-kolom ini dijelaskan dalam tabel berikut:

Header kolom CSV Wajib Diisi atau Opsional Nilai yang diterima
Nama Wajib Maksimum 100 karakter
Deskripsi Opsional Maksimum 500 karakter
Nilai Inkremental Opsional True atau False
Langkah yang Diperlukan Wajib jika Incremental Value adalah True. Angka (tanpa pecahan atau desimal)
Keadaan Awal Wajib Hidden atau Revealed
Poin Wajib Angka yang merupakan kelipatan 5, dan nilainya harus antara 5 dan 200
Urutan Daftar Opsional Angka (tanpa pecahan atau desimal, dan lebih besar dari nol)

Persyaratan file AchievementsMetadata.csv:

  • Setiap baris harus memiliki tujuh nilai. Jika Anda ingin menghapus nilai, kosongkan nilai tersebut.
  • Kolom Name dan Description digunakan sebagai lokalitas default.
  • Kolom Name harus unik di semua pencapaian.
  • Kolom berikut tidak boleh berisi koma: Name dan Description.

Contoh file AchievementsMetadata.csv:

  Achievement1,Achievement One,True,100,Hidden,5,20
  Achievement2,Achievement Two,False,,Revealed,10,30
Format AchievementsLocalizations.csv

File AchievementsLocalizations.csv adalah file opsional yang menyiapkan semua data yang diperlukan untuk mendeskripsikan setiap pencapaian kepada pengguna di lokalitas yang berbeda. Pencapaian diterjemahkan sesuai dengan lokalitas yang ditentukan untuk game.

File ini harus menyertakan informasi sebagai nilai yang dipisahkan koma dalam urutan berikut: 

   Name, Localized name, Localized description, locale

Kolom-kolom ini dijelaskan dalam tabel berikut:

Header kolom CSV Wajib Diisi atau Opsional Deskripsi Nilai yang diterima
Nama Wajib Harus cocok dengan kolom Name dari AchievementsMetadata.csv. Maksimum 100 karakter
Nama yang dilokalkan Wajib Nama yang dilokalkan untuk pencapaian. Maksimum 100 karakter
Deskripsi yang dilokalkan Opsional Deskripsi yang dilokalkan untuk pencapaian dalam lokalitas yang ditentukan. Maksimum 500 karakter
Lokal Wajib Kode lokalitas seperti en-US. Tambahkan terjemahan untuk game Anda sebelum menentukan lokalitas. Perhatikan bahwa Anda tidak dapat menentukan lokalitas default.

Kode lokalitas yang didukung dapat ditemukan dalam daftar bahasa yang didukung.

Persyaratan file AchievementsLocalizations.csv:

  • Nama pencapaian dalam game harus unik per lokalitas.

    Misalnya, jika game mendukung lokalitas en-US dan fr-FR, pencapaian yang bernama "Achievement1" untuk en-US juga dapat diberi nama "Achievement1" untuk fr-FR.

  • Setiap baris harus memiliki empat nilai. Jika Anda ingin menghapus nilai Deskripsi yang dilokalkan, kosongkan nilai tersebut.

Contoh file AchievementsLocalizations.csv:

Achievement1,Achievement One,This is the description of achievement one in English.,en-US
Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR
Achievement2,Achievement Two,Description of achievement two.,en-US
Achievement2,Logro Dos,Descripción del logro dos.,es-ES
Achievement3,Achievement Three,,en-US
Achievement3,Erfolg Drei,,de-DE
Format AchievementsIconMappings.csv

File AchievementsIconMappings.csv adalah file opsional yang digunakan untuk memetakan pencapaian Anda dengan ikon yang diberikan. File ini harus menyertakan informasi sebagai nilai yang dipisahkan koma dalam urutan berikut: 

Name, icon filename

Kolom-kolom ini dijelaskan dalam tabel berikut

Header kolom CSV Wajib Diisi atau Opsional Deskripsi
Nama Wajib Harus cocok dengan kolom Name dari AchievementsMetadata.csv.
Nama file ikon Wajib Nama file ikon Anda.

Persyaratan file AchievementsIconMappings.csv:

  • Setiap baris harus memiliki dua nilai.
  • File ikon hanya boleh dalam format PNG atau JPEG.

Contoh fileAchievementsIconMappings.csv:

Valid Achievement,valid-achievement-icon.png
Incremental Achievement,incremental-achievement-icon.jpeg
No Description,no-description-icon.png
Hidden Initial State,hidden-initial-state-icon.png
Large Point Value,large-point-value-icon.jpeg

Pedoman ikon

Ikon harus dibuat sebagai file PNG, JPEG, atau JPG berukuran 512 x 512. Anda hanya perlu memberikan ikon untuk pencapaian terbuka. Kami akan secara otomatis membuat versi hitam putih untuk ikon yang ditampilkan. Oleh karena itu, sebaiknya ikon pencapaian Anda menyertakan elemen yang berwarna-warni, sehingga pengguna dapat dengan mudah membedakan antara pencapaian terungkap dan pencapaian terbuka.

Saat ikon pencapaian ditampilkan dalam [toast][a] Android, ikon akan di-overlay dengan lingkaran dan sudut-sudut luarnya tersembunyi. Pastikan ikon Anda masih terlihat bagus dalam kondisi ini.

Contoh ikon pencapaian.
Contoh ikon pencapaian.

Ikon yang sama digunakan di semua lokalitas, jadi sebaiknya jangan sertakan teks atau konten yang dilokalkan dalam ikon.

File ikon

Ikon yang Anda referensikan dalam file AchievementsIconMappings.csv harus ada dalam arsip zip saat ini yang Anda impor.

Memperbarui game dengan pencapaian yang ada

Anda dapat menambahkan lebih banyak pencapaian ke game dan memperbarui pencapaian yang ada di Konsol Google Play.

Menambahkan pencapaian lainnya

Jika Anda sudah memiliki pencapaian dan ingin menambahkan pencapaian lainnya:

  1. Di Konsol Google Play, pilih game.
  2. Di halaman Layanan game Play - Pencapaian (Mendorong pertumbuhan > Layanan game Play > Penyiapan dan pengelolaan > Pencapaian), pilih Tambahkan pencapaian.
Mengedit pencapaian

Jika Anda sudah memiliki pencapaian dan ingin mengeditnya:

  1. Di Konsol Google Play, pilih game.
  2. Di halaman Layanan game Play - Pencapaian (Mendorong pertumbuhan > Layanan game Play > Penyiapan dan pengelolaan > Pencapaian), pilih pencapaian.
  3. Anda dapat mengedit kolom apa pun.
  4. Klik Simpan sebagai draf.
  5. Di halaman Layanan game Play - Pencapaian, pencapaian yang diedit berstatus "Tersedia untuk penguji".
  6. Setelah Anda menguji pencapaian, klik Tinjau dan publikasikan.

    Tindakan ini akan memublikasikan ulang game Anda, beserta semua pencapaian terbaru Anda.
Menghapus pencapaian

Setelah dipublikasikan, pencapaian Anda tidak dapat dihapus. Anda hanya dapat menghapus pencapaian dalam status pra-publikasi

  1. Di halaman Layanan game Google Play - Pencapaian, pilih pencapaian.
  2. Untuk menghapus pencapaian, klik hapus pencapaian.
Mereset pencapaian

Anda hanya dapat mereset data progres pemain untuk pencapaian draf.

  1. Di halaman Layanan game Google Play - Pencapaian, pilih pencapaian.
  2. Untuk mereset pencapaian, klik Reset progres.
  3. Untuk mereset data pencapaian secara terprogram, panggil metode Achievements Management API.

Menambahkan terjemahan untuk pencapaian

Anda dapat menentukan terjemahan Anda sendiri untuk pencapaian yang terkait dengan game Anda. Sebelum melakukannya, pastikan Anda sudah menyelesaikan langkah-langkah yang dijelaskan dalam Menambahkan terjemahan untuk game.

Ada dua cara untuk menambahkan terjemahan game:

  • Anda dapat menggunakan opsi impor pencapaian untuk mengupload terjemahan untuk banyak pencapaian baru sekaligus. Anda tidak dapat menggunakan opsi ini untuk mengupload terjemahan pencapaian yang sudah ada.

  • Anda dapat menambahkan terjemahan untuk setiap pencapaian dalam game. Untuk menambahkan terjemahan Anda sendiri untuk setiap pencapaian:

    1. Di Konsol Google Play, buka tab Pencapaian untuk game Anda, lalu pilih pencapaian yang sudah ada.
    2. Di halaman detail pencapaian, pilih tab untuk bahasa yang sebelumnya Anda tambahkan di tab Detail game.
    3. Di halaman detail pencapaian untuk bahasa tersebut, edit formulir yang berisi terjemahan untuk pencapaian tersebut.
    4. Klik Simpan untuk menyimpan detail pencapaian yang telah diterjemahkan.

Implementasi klien

Untuk mempelajari cara mengimplementasikan pencapaian untuk platform Anda, lihat referensi berikut:

Menguji pencapaian

Untuk memastikan bahwa pencapaian berfungsi sebagaimana mestinya, ikuti langkah-langkah untuk mengujinya:

  • Siapkan jalur pengujian internal.
  • Tambahkan akun uji ke project game Anda untuk penguji.
  • Buat profil Layanan game Play untuk salah satu akun pengujian menggunakan Aplikasi Play Game.
  • Buka game menggunakan akun pengujian yang sama dengan yang Anda gunakan untuk membuat profil Layanan game Play.
  • Verifikasi bahwa "Toast selamat datang" Layanan game Play ditampilkan di layar sebagai konfirmasi keberhasilan autentikasi otomatis saat peluncuran game.
  • Mainkan game dan selesaikan langkah-langkah yang diperlukan untuk membuka pencapaian.

  • Untuk memverifikasi pencapaian:

    • Pastikan pop-up "pencapaian dibuka" ditampilkan di layar saat pencapaian diselesaikan.

    • Buka aplikasi Play Store dan verifikasi bahwa bagian pencapaian di YouTab menampilkan pencapaian yang telah diselesaikan dan yang sedang berlangsung (dengan detail progres).

Melacak performa pencapaian di Konsol Play

Berikut cara menemukan statistik singkat untuk pencapaian individu:

  • Di Konsol Google Play.
  • Buka Setelan> Project game.
  • Pilih game.
  • Di menu sebelah kiri, klik Pencapaian.
  • Di halaman Pencapaian, Anda dapat menemukan statistik untuk memahami apakah pemain membuka kunci pencapaian. Untuk pencapaian yang tidak disembunyikan, Anda dapat melihat persentase pengguna yang membukanya. Untuk pencapaian tahap awal, persentase pembukaan biasanya mendekati 100%.

Anda juga dapat melacak performa deret waktu pencapaian di halaman Kembangkan > Layanan game Play > Statistik game.

Publikasikan pencapaian

Setelah selesai menguji, Anda harus memublikasikan game. Semua pencapaian game Anda dipublikasikan bersama game tersebut. Memublikasikan pencapaian adalah langkah yang diperlukan agar pencapaian berfungsi dengan baik.

Untuk memublikasikan, ikuti langkah-langkah berikut:

  1. Di Konsol Google Play, pilih game.
  2. Di halaman Layanan game Play - Pencapaian (Mendorong pertumbuhan > Layanan game Play > Penyiapan dan pengelolaan > Pencapaian), klik Tinjau dan publikasikan.
  3. Di halaman Layanan game Play - Publikasi (Mendorong pertumbuhan > Layanan game Play > Penyiapan dan pengelolaan > Publikasi), tinjau tindakan dan perbaiki masalah.
  4. Klik Publikasikan.

    Semua pencapaian game Anda dipublikasikan.

Kesalahan umum yang harus dihindari

Poin-poin ini menyoroti kesalahan umum yang harus dihindari saat menerapkan pencapaian dalam game. Mereka menekankan pentingnya:

  • Di Konsol Play, buka Mendorong pertumbuhan > Layanan game Play > Penyiapan dan pengelolaan > Pencapaian.

    • Sebelum memublikasikan, pastikan pencapaian yang dikonfigurasi di Konsol Play tidak dalam status "Draf".
    • Jangan menambahkan nilai ID pencapaian dari Konsol Play ke kode game. Sebagai gantinya, gunakan implementasi klien.

  • Pastikan Anda juga telah menerapkan logika buka kunci di klien Anda.

    • Pemain tidak dapat melewati langkah pemicu saat API pembuka kunci dipanggil. Misalnya, menyelesaikan tutorial adalah pencapaian, tetapi pemain dapat melewati tutorial itu sendiri.