Chat App Message Service:Praktik terbaik untuk templat otentikasi

Informasi latar belakang

Pada 1 Mei 2023, WhatsApp meluncurkan templat otentikasi dengan tombol kata sandi sekali pakai (OTP). Mulai 29 Mei 2023, semua templat otentikasi baru harus mencakup tombol OTP. Untuk informasi lebih lanjut tentang templat otentikasi WhatsApp, lihat Templat Pesan WhatsApp.

Templat otentikasi

Komposisi

Templat otentikasi dengan tombol OTP terdiri dari konten berikut:

• Teks preset:

  • <VERIFICATION_CODE> adalah kode verifikasi Anda.

  • Pernyataan keamanan (opsional): Untuk keamanan Anda, jangan bagikan kode ini.

  • Peringatan kedaluwarsa (opsional): Kode ini akan kedaluwarsa dalam <NUM_MINUTES> menit.

• Tombol: tombol salin kode atau tombol pengisian otomatis satu ketukan

Contoh:

Batasan

• Templat otentikasi dengan tombol OTP hanya terdiri dari teks preset dan tombol.

• URL, sumber media, dan emoji tidak dapat ditentukan sebagai konten atau parameter templat otentikasi. Sumber media mencakup gambar, audio, video, dan file.

• Kode verifikasi yang dikirim menggunakan templat otentikasi dapat memiliki panjang hingga 15 karakter.

Tombol

Templat otentikasi harus mencakup tombol salin kode atau tombol pengisian otomatis satu ketukan. Tombol-tombol tersebut bekerja secara berbeda saat ditekan oleh pengguna.

• Tombol salin kode: Pengguna menekan tombol ini untuk menyalin OTP atau kode verifikasi ke clipboard. Kemudian, pengguna beralih ke aplikasi Anda dan menempelkan OTP atau kode verifikasi ke antarmuka aplikasi.

• Tombol pengisian otomatis satu ketukan: Setelah pengguna menekan tombol ini, aplikasi Anda dimuat secara otomatis, dan OTP atau kode verifikasi diteruskan ke aplikasi.

Disarankan untuk menggunakan tombol pengisian otomatis satu ketukan karena memberikan pengalaman pengguna terbaik. Hanya Android yang mendukung tombol pengisian otomatis satu ketukan. Selain itu, jika ingin menggunakan tombol ini, Anda harus mengubah kode aplikasi untuk melakukan handshake dan mengubah hash kunci penandatanganan aplikasi. Untuk informasi lebih lanjut, lihat bagian Handshake dan Hash Kunci Penandatanganan Aplikasi dalam topik ini.

Praktik terbaik

• Konfirmasikan nomor telepon WhatsApp sebelum mengirim OTP atau kode verifikasi.

• Jelaskan kepada pengguna bahwa OTP atau kode verifikasi akan dikirim ke nomor telepon WhatsApp mereka, terutama jika Anda memberikan opsi lain untuk menerima OTP atau kode verifikasi.

• Jika pengguna menempelkan OTP atau kode verifikasi ke aplikasi Anda, atau aplikasi Anda menerima OTP atau kode verifikasi yang diteruskan oleh tombol pengisian otomatis satu ketukan, pastikan kepada pengguna bahwa aplikasi Anda telah menerima kata sandi atau kode tersebut.

Parameter

Hash kunci penandatanganan aplikasi

Jika Anda ingin membuat templat otentikasi yang menggunakan tombol pengisian otomatis satu ketukan, Anda harus menyertakan hash kunci penandatanganan aplikasi Anda dalam array komponen.

Untuk menghitung hash Anda, ikuti instruksi yang diberikan oleh Google di Menghitung String Hash Aplikasi Anda.

Jika Anda mengunduh sertifikat kunci penandatanganan aplikasi sesuai instruksi Google, Anda dapat menggunakan sertifikat tersebut bersama dengan skrip shell sms_retriever_hash_v9.sh untuk menghitung hash.

Handshake

Jika pengguna aplikasi Anda meminta OTP atau kode verifikasi dan memilih untuk mengirim OTP atau kode verifikasi ke nomor telepon WhatsApp, Anda perlu melakukan handshake dan memanggil API kami untuk mengirim pesan templat otentikasi. Setelah aplikasi WhatsApp atau WhatsApp Business menerima pesan, aplikasi tersebut akan memeriksa apakah pesan tersebut memenuhi syarat. Jika pesan lulus pemeriksaan kelayakan, aplikasi WhatsApp akan memulai intent dan menampilkan pesan kepada pengguna. Saat pengguna menekan tombol pengisian otomatis satu ketukan dalam pesan, aplikasi WhatsApp memuat aplikasi Anda dan meneruskan kata sandi atau kode verifikasi ke aplikasi Anda.

Pemeriksaan kelayakan

Setelah aplikasi WhatsApp atau WhatsApp Business menerima pesan templat otentikasi, aplikasi tersebut memeriksa item yang dijelaskan dalam bagian berikut. Jika pemeriksaan gagal, tombol pengisian otomatis satu ketukan akan diganti dengan tombol salin kode.

• Handshake dimulai dalam waktu 10 menit sebelum pesan dikirim.

• Nama paket aplikasi yang terkandung dalam pesan cocok dengan nama paket aplikasi yang disetel pada intent. Nama paket aplikasi yang terkandung dalam pesan adalah nilai package_name dalam array komponen yang disetel saat Anda membuat templat otentikasi. Aplikasi WhatsApp atau WhatsApp Business menentukan apakah nama paket aplikasi cocok dengan menggunakan metode getCreatorPackage yang dipanggil dalam objek PendingIntent yang disediakan oleh aplikasi Anda.

• Hash kunci penandatanganan aplikasi dalam pesan cocok dengan hash kunci penandatanganan aplikasi Anda. Hash kunci penandatanganan aplikasi dalam pesan adalah nilai signature_hash dalam array komponen yang disetel saat Anda membuat templat otentikasi.

• Pesan berisi teks tombol pengisian otomatis satu ketukan.

• Aplikasi Anda telah mendefinisikan aktivitas untuk menerima kata sandi atau kode verifikasi. Untuk informasi lebih lanjut, lihat bagian Aktivitas dalam topik ini.

Notifikasi Android

Notifikasi Android yang menunjukkan bahwa pengguna telah menerima pesan templat otentikasi WhatsApp akan muncul di perangkat Android pengguna hanya dalam situasi berikut:

• Pengguna masuk ke aplikasi WhatsApp atau WhatsApp Business dengan nomor telepon atau akun yang menerima pesan.

• Pengguna masuk ke aplikasi Anda.

• Sistem operasi Android adalah KitKat (4.4, API 19) atau versi lebih baru.

• Tampilkan notifikasi diaktifkan di bawah Pengaturan > Notifikasi dalam aplikasi WhatsApp atau WhatsApp Business.

• Notifikasi tingkat perangkat diaktifkan untuk aplikasi WhatsApp atau WhatsApp Business.

• Pesan sebelumnya dalam aplikasi WhatsApp atau WhatsApp Business antara pengguna dan perusahaan Anda tidak dibisukan.

Implementasi klien

Bagian berikut menjelaskan cara mengimplementasikan aktivitas dan kelas dalam aplikasi Anda.

Aktivitas

Nyatakan aktivitas dan filter intent yang dapat menerima OTP atau kode verifikasi. Filter intent harus berisi nama aksi com.whatsapp.otp.OTP_RETRIEVED.

Aplikasi WhatsApp atau WhatsApp Business akan segera memulai aktivitas setelah pesan templat otentikasi diterima dan pesan tersebut lulus semua pemeriksaan kelayakan.

Kelas publik

Definisikan kelas aktivitas publik yang dapat menerima OTP atau kode verifikasi yang diteruskan ke aplikasi Anda.

Memulai handshake

Contoh berikut menunjukkan cara memulai handshake menggunakan aplikasi WhatsApp atau WhatsApp Business:

public void sendOtpIntentToWhatsApp() {
   // Kirim intent OTP_REQUESTED ke WA dan WA Business App
   sendOtpIntentToWhatsApp("com.whatsapp");
   sendOtpIntentToWhatsApp("com.whatsapp.w4b");
}

private void sendOtpIntentToWhatsApp(String packageName) {

  /**
  * Dimulai dengan Build.VERSION_CODES.S, akan diperlukan untuk secara eksplisit 
  * menentukan mutabilitas PendingIntents pada pembuatan dengan salah satu 
  * (@link #FLAG_IMMUTABLE} atau FLAG_MUTABLE
  */
  int flags = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ? FLAG_IMMUTABLE : 0;
  PendingIntent pi = PendingIntent.getActivity(
      getApplicationContext(), 
      0, 
      new Intent(), 
      flags);


  // Kirim intent OTP_REQUESTED ke WhatsApp
  Intent intentToWhatsApp = new Intent();
  intentToWhatsApp.setPackage(packageName);
  intentToWhatsApp.setAction("com.whatsapp.otp.OTP_REQUESTED");
  // WA akan menggunakan ini untuk memverifikasi identitas aplikasi pemanggil.
  Bundle extras = intentToWhatsApp.getExtras();
  if (extras == null) {
     extras = new Bundle();
  }
  extras.putParcelable("_ci_", pi);
  intentToWhatsApp.putExtras(extras);
  getApplicationContext().sendBroadcast(intentToWhatsApp);
}

Sinyal kesalahan

Jika pesan Anda gagal dalam pemeriksaan kelayakan, tombol pengisian otomatis satu ketukan akan diganti dengan tombol salin kode. Selain itu, notifikasi pesan mungkin diblokir oleh perangkat, aplikasi WhatsApp, atau WhatsApp Business. Untuk membantu Anda melakukan debugging, aplikasi WhatsApp atau WhatsApp Business menampilkan beberapa informasi kesalahan menggunakan intent com.whatsapp.OTP_ERROR. Dalam hal ini, Anda akan menerima kunci kesalahan dan pesan alih-alih OTP atau kode verifikasi.

Beberapa sinyal kesalahan hanya ditampilkan jika Anda menjalankan aplikasi WhatsApp atau WhatsApp Business di emulator Android.

Integrasi

Sinyal kesalahan dikirim menggunakan intent siaran. Oleh karena itu, Anda harus mengimplementasikan BroadcastReceiver untuk menerima sinyal kesalahan.

Di manifest.xml

<receiver
 android:name=".app.otp.OtpErrorReceiver"
 android:enabled="true"
 android:exported="true" >
   <intent-filter>
       <action android:name="com.whatsapp.otp.OTP_ERROR"/>
   </intent-filter>
</receiver>

Di kelas penerima

<![CDATA[ public class OtpErrorReceiver extends BroadcastReceiver { public static final String OTP_ERROR_KEY = "error"; public static final String OTP_ERROR_MESSAGE_KEY = "error_message"; @Override public void onReceive(Context context, Intent intent) { try { PendingIntent pendingIntent = intent.getParcelableExtra("_ci_"); if (pendingIntent != null) { String packageName = pendingIntent.getCreatorPackage(); if (packageName.equalsIgnoreCase("com.whatsapp") || packageName.equalsIgnoreCase("com.whatsapp.w4b")) { String otpErrorKey = intent.getStringExtra(OTP_ERROR_KEY);String otpErrorMessage = intent.getStringExtra(OTP_ERROR_MESSAGE_KEY); // Tangani kesalahan } } } catch (BadParcelableException e) { Log.e("OtpErrorReceiver", e.getLocalizedMessage()); } } } ]]>

Aplikasi contoh

Untuk informasi lebih lanjut tentang aplikasi contoh untuk Android, lihat Aplikasi Contoh Kata Sandi Sekali Pakai (OTP) WhatsApp di GitHub. Aplikasi contoh menunjukkan cara mengirim dan menerima OTP dan kode verifikasi menggunakan operasi API, cara mengintegrasikan tombol pengisian otomatis satu ketukan dan tombol salin kode, cara membuat templat, dan cara memulai server contoh.