Chat App Message Service:認証テンプレートのベストプラクティス

背景情報

2023 年 5 月 1 日、WhatsApp はワンタイムパスワード（OTP）ボタンを含む認証テンプレートを導入しました。 2023 年 5 月 29 日以降、すべての新しい認証テンプレートには OTP ボタンが含まれている必要があります。 WhatsApp 認証テンプレートの詳細については、「WhatsApp メッセージテンプレート」をご参照ください。

認証テンプレート

構成

OTP ボタン付きの認証テンプレートは、次のコンテンツで構成されています。

• 事前設定テキスト:

  • <VERIFICATION_CODE> はお客様の確認コードです。

  • セキュリティに関する免責事項（オプション）: セキュリティのため、このコードを共有しないでください。

  • 有効期限の警告（オプション）: このコードは <NUM_MINUTES> 分で期限切れになります。

• ボタン: コードのコピーボタンまたはワンタップ自動入力ボタン

例:

制限事項

• OTP ボタン付きの認証テンプレートは、事前設定テキストとボタンのみで構成されます。

• URL、メディアリソース、絵文字は、認証テンプレートのコンテンツまたはパラメーターとして指定できません。 メディアリソースには、画像、音声、動画、ファイルが含まれます。

• 認証テンプレートを使用して配信される確認コードは、最大 15 文字までです。

ボタン

認証テンプレートには、コードのコピーボタンまたはワンタップ自動入力ボタンが含まれている必要があります。 これらのボタンは、ユーザーがタップしたときの動作が異なります。

• コードのコピーボタン: ユーザーがこのボタンをタップすると、OTP または確認コードがクリップボードにコピーされます。 次に、ユーザーはアプリに切り替えて、OTP または確認コードをアプリのインターフェースに貼り付けます。

• ワンタップ自動入力ボタン: ユーザーがこのボタンをタップすると、アプリが自動的に読み込まれ、OTP または確認コードがアプリに渡されます。

最適なユーザーエクスペリエンスが提供されるため、ワンタップ自動入力ボタンを使用することをお勧めします。 ワンタップ自動入力ボタンは Android でのみサポートされています。 また、ワンタップ自動入力ボタンを使用する場合は、ハンドシェイクを実行するようにアプリコードを変更し、アプリの署名キーハッシュを変更する必要があります。 詳細については、このトピックの ハンドシェイク セクションと アプリ署名キーハッシュ セクションをご参照ください。

ベストプラクティス

• OTP または確認コードを送信する前に、WhatsApp の電話番号を確認します。

• 特に、OTP または確認コードを受信するための複数のオプションをユーザーに提供する場合、OTP または確認コードが WhatsApp の電話番号に配信されることをユーザーに明確に伝えます。

• ユーザーが OTP または確認コードをアプリに貼り付ける場合、またはアプリがワンタップ自動入力ボタンによって渡された OTP または確認コードを受信する場合は、アプリがパスワードまたはコードを受信したことをユーザーに明確に伝えます。

パラメーター

アプリ署名キーハッシュ

ワンタップ自動入力ボタンを使用する認証テンプレートを作成する場合は、コンポーネント配列にアプリ署名キーハッシュを含める必要があります。

ハッシュを計算するには、Google が アプリのハッシュ文字列の計算 で提供している手順に従ってください。

Google の指示に従ってアプリ署名キー証明書をダウンロードする場合は、証明書と sms_retriever_hash_v9.sh シェルスクリプトを一緒に使用してハッシュを計算できます。

ハンドシェイク

アプリのユーザーが OTP または確認コードをリクエストし、OTP または確認コードを WhatsApp の電話番号に配信することを選択した場合、ハンドシェイクを実行し、API を呼び出して認証テンプレートメッセージを送信する必要があります。 WhatsApp アプリまたは WhatsApp Business アプリがメッセージを受信すると、メッセージが適格かどうかがチェックされます。 メッセージが適格性チェックに合格すると、WhatsApp アプリはインテントを開始し、メッセージをユーザーに表示します。 ユーザーがメッセージ内のワンタップ自動入力ボタンをタップすると、WhatsApp アプリはアプリを読み込み、パスワードまたは確認コードをアプリに渡します。

適格性チェック

WhatsApp アプリまたは WhatsApp Business アプリが認証テンプレートメッセージを受信すると、次のセクションで説明されている項目がチェックされます。 チェックに失敗した場合、ワンタップ自動入力ボタンはコードのコピーボタンに置き換えられます。

• ハンドシェイクは、メッセージが送信される 10 分前までに開始されます。

• メッセージに含まれるアプリパッケージ名は、インテントに設定されているアプリパッケージ名と一致します。 メッセージに含まれるアプリパッケージ名は、認証テンプレートの作成時に設定される components 配列の package_name の値です。 WhatsApp アプリまたは WhatsApp Business アプリは、アプリによって提供される PendingIntent オブジェクトで呼び出される getCreatorPackage メソッドを使用して、アプリパッケージ名が一致するかどうかを判断します。

• メッセージ内のアプリ署名キーハッシュは、アプリの署名キーハッシュと一致します。 メッセージ内のアプリ署名キーハッシュは、認証テンプレートの作成時に設定される components 配列の signature_hash の値です。

• メッセージには、ワンタップ自動入力ボタンのテキストが含まれています。

• アプリは、パスワードまたは確認コードを受信するアクティビティを定義しています。 詳細については、このトピックの アクティビティ セクションをご参照ください。

Android 通知

ユーザーが WhatsApp 認証テンプレートメッセージを受信したことを示す Android 通知は、次の場合にのみユーザーの Android デバイスに表示されます。

• ユーザーがメッセージを受信する電話番号またはアカウントで WhatsApp アプリまたは WhatsApp Business アプリにログインしている。

• ユーザーがアプリにログインしている。

• Android オペレーティングシステムが KitKat（4.4、API 19）以降である。

• WhatsApp アプリまたは WhatsApp Business アプリの [設定] > [通知] で [通知を表示] が有効になっている。

• WhatsApp アプリまたは WhatsApp Business アプリのデバイスレベルの通知が有効になっている。

• WhatsApp アプリまたは WhatsApp Business アプリで、ユーザーと企業間の以前のメッセージがミュートされていない。

クライアント実装

次のセクションでは、アプリにアクティビティとクラスを実装する方法について説明します。

アクティビティ

OTP または確認コードを受信できるアクティビティとインテントフィルターを宣言します。 インテントフィルターには、アクション名 com.whatsapp.otp.OTP_RETRIEVED が含まれている必要があります。

WhatsApp アプリまたは WhatsApp Business アプリは、認証テンプレートメッセージが受信され、メッセージがすべての 適格性チェック に合格した直後に、アクティビティを開始します。

パブリッククラス

アプリに渡される OTP または確認コードを受け入れることができるアクティビティパブリッククラスを定義します。

ハンドシェイクを開始する

次の例は、WhatsApp アプリまたは WhatsApp Business アプリを使用してハンドシェイクを開始する方法を示しています。

public void sendOtpIntentToWhatsApp() {
   // Send OTP_REQUESTED intent to both WA and WA Business App // OTP_REQUESTED インテントを WA と WA Business アプリの両方に送信します
   sendOtpIntentToWhatsApp("com.whatsapp");
   sendOtpIntentToWhatsApp("com.whatsapp.w4b");
}

private void sendOtpIntentToWhatsApp(String packageName) {

  /**
  * Starting with Build.VERSION_CODES.S, it will be required to explicitly 
  * specify the mutability of  PendingIntents on creation with either 
  * (@link #FLAG_IMMUTABLE} or FLAG_MUTABLE
  */
  // Build.VERSION_CODES.S 以降、PendingIntents の変更可能性を (@link #FLAG_IMMUTABLE} または FLAG_MUTABLE のいずれかで明示的に指定する必要があります。
  int flags = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S ? FLAG_IMMUTABLE : 0;
  PendingIntent pi = PendingIntent.getActivity(
      getApplicationContext(), 
      0, 
      new Intent(), 
      flags);


  // Send OTP_REQUESTED intent to WhatsApp // OTP_REQUESTED インテントを WhatsApp に送信します
  Intent intentToWhatsApp = new Intent();
  intentToWhatsApp.setPackage(packageName);
  intentToWhatsApp.setAction("com.whatsapp.otp.OTP_REQUESTED");
  // WA will use this to verify the identity of the caller app. // WA はこれを使用して、呼び出し元アプリの ID を検証します。
  Bundle extras = intentToWhatsApp.getExtras();
  if (extras == null) {
     extras = new Bundle();
  }
  extras.putParcelable("_ci_", pi);
  intentToWhatsApp.putExtras(extras);
  getApplicationContext().sendBroadcast(intentToWhatsApp);
}

エラーシグナル

メッセージが適格性チェックに失敗した場合、ワンタップ自動入力ボタンはコードのコピーボタンに置き換えられます。 また、メッセージ通知がデバイス、WhatsApp アプリ、または WhatsApp Business アプリによってブロックされる場合があります。 デバッグを実行するのに役立つように、WhatsApp アプリまたは WhatsApp Business アプリは、com.whatsapp.OTP_ERROR インテントを使用してエラー情報を表示します。 この場合、OTP または確認コードではなく、エラーキーとメッセージを受信します。

一部のエラーシグナルは、Android エミュレーターで WhatsApp アプリまたは WhatsApp Business アプリを実行している場合にのみ表示されます。

統合

エラーシグナルはブロードキャストインテントを使用して配信されます。 そのため、エラーシグナルを受信するには、BroadcastReceiver を実装する必要があります。

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>

レシーバークラス

<![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); // Handle errors // エラーを処理します } } } catch (BadParcelableException e) { Log.e("OtpErrorReceiver", e.getLocalizedMessage()); } } } ]]>

サンプルアプリ

Android 用のサンプルアプリの詳細については、GitHub の WhatsApp ワンタイムパスワード（OTP）サンプルアプリ をご参照ください。 サンプルアプリは、API 操作を使用して OTP と確認コードを送受信する方法、ワンタップ自動入力ボタンとコードのコピーボタンを統合する方法、テンプレートを作成する方法、サンプルサーバーを起動する方法を示しています。