Chat APP Message Service：身分識別驗證模板最佳實務

背景資訊

自2023年5月1日起，WhatsApp推出了包含單次密碼按鈕的身分識別驗證模板（Authentication），自2023年5月29日起，所有建立的身分識別驗證模板都必須包含單次密碼按鈕。更多關於身分識別驗證模板的資訊請參見WhatsApp模板類型說明。

身分識別驗證模板

模板組成

包含單次密碼按鈕的身分識別驗證模板由以下部分組成：

• 身分識別驗證模板的預設固定文本：

  • <VERIFICATION_CODE> 是您的驗證碼。

  • 安全免責聲明（可選）：為安全起見，請勿共用該驗證碼。

  • 到期警告（可選）：這組驗證碼將在<NUM_MINUTES>分鐘後到期。

• 按鈕：複製驗證碼按鈕（Copy code）或一鍵自動填寫按鈕（Autofill）。

樣本圖：

模板規則限制

• 包含單次密碼按鈕的身分識別驗證模板僅由預設文本和按鈕組成。

• 身分識別驗證模板的內容或參數不允許使用網址、媒體（圖片、音頻、視頻、檔案等）和Emoji。

• 身分識別驗證模板使用參數最多支援15 個字元，即驗證碼最大長度為15位。

按鈕

身分識別驗證模板必須包含複製驗證碼按鈕（Copy code）或一鍵自動填寫按鈕（Autofill）。當使用者點擊按鈕時，不同按鈕的工作方式不同：

• 複製驗證碼按鈕：會將單次密碼或驗證碼複製到使用者的剪貼簿。然後，使用者可以手動切換到您的應用，將單次密碼或驗證碼粘貼到應用介面。

• 一鍵自動填寫按鈕：會自動載入您的應用，並向該應用傳遞單次密碼或驗證碼。

一鍵自動填寫按鈕可提供最佳使用者體驗，所以是首選的解決方案。但是，目前僅安卓系統手機（Android）支援一鍵自動填寫按鈕，並且此類按鈕需要更改您應用的代碼，才能執行“握手”，另外還需要更改應用的簽名密鑰雜湊值。請參閱下方握手和 應用簽名密鑰雜湊值部分。

最佳實務

• 在發送單次密碼或驗證碼前，先確認使用者的WhatsApp電話號碼，再向該號碼發送單次密碼或驗證碼。

• 明確告知使用者，單次密碼或驗證碼將發送至他們的WhatsApp電話號碼，尤其是當您為使用者提供多種方式來接收單次密碼或驗證碼時。

• 當使用者將單次密碼或驗證碼粘貼到您的應用中時，或應用在一鍵自動填寫按鈕流程中收到單次密碼或驗證碼時，請明確告知使用者應用已擷取單次密碼或驗證碼。

參數說明

應用簽名密鑰雜湊值

如要建立使用一鍵自動填寫按鈕的身分識別驗證模板，您必須在components數組中加入應用簽名密鑰雜湊值。

如要計算您的雜湊值，請遵循Google有關計算應用的雜湊字串的說明。

或者，如果您按照Google說明下載了應用簽名密鑰認證，您可以結合使用該認證和sms_retriever_hash_v9.sh shell指令碼來計算雜湊值。

握手

如果您應用中的使用者請求擷取單次密碼或驗證碼，並選擇將其發送到他們的WhatsApp電話號碼，您首先應執行“握手”，然後調用我們的API來發送身分識別驗證模板訊息。在收到該訊息後，WhatsApp應用將執行資格檢查。如果沒有錯誤，WhatsApp將啟動意圖並向使用者顯示該訊息。最後，當使用者點擊該訊息的一鍵自動填寫按鈕時，WhatsApp應用會自動載入您的應用並向傳遞單次密碼或驗證碼。

資格檢查

在收到身分識別驗證模板訊息之後，WhatsApp應用會執行以下檢查。如果任意檢查失敗，一鍵自動填寫按鈕將被替換為複製驗證碼按鈕。

• “握手”是在發送訊息前的10分鐘內發起。

• 訊息中的應用程式套件名（建立模板時在components數組的package_name屬性中定義）與意圖上設定的應用程式套件名匹配。WhatsApp應用將使用您的應用程式提供的PendingIntent對象中調用的getCreatorPackage方法判斷專案包名稱是否匹配。

• 訊息中的應用簽名密鑰雜湊值（建立模板時在components數組的signature_hash屬性中定義）與您所安裝應用的簽名密鑰雜湊值匹配。

• 訊息包含一鍵自動填寫按鈕的文本。

• 您的應用已定義用於接收單次密碼或驗證碼的活動。請參閱下方活動（Activity）部分。

Android通知

僅在以下情況下，表示已收到WhatsApp身分識別驗證模板訊息的Android通知才會顯示在使用者的Android裝置上：

• 使用者使用所發送訊息的接收電話號碼（賬戶）登入WhatsApp應用。

• 使用者登入您的應用。

• Android作業系統是 KitKat（Android 4.4，API 19）或更高版本。

• WhatsApp應用已啟用顯示通知（設定>通知）。

• 已為WhatsApp應用啟用裝置層級通知。

• 在WhatsApp應用中，使用者與您的企業之間過去的訊息對話未設為靜音。

用戶端實現

在您的應用中實現以下活動（activity）和類（class）。

活動（Activity）

聲明可接收單次密碼或驗證碼的活動和意圖篩選條件。意圖篩選條件必須具有操作名稱 com.whatsapp.otp.OTP_RETRIEVED。

在收到身分識別驗證模板訊息（且該訊息已通過所有資格檢查）後，WhatsApp應用將立即開始執行此活動。

公用類（Public Class）

定義在單次密碼或驗證碼傳遞到您的應用後，可接受該單次密碼或驗證碼的活動公用類。

發起“握手”

以下樣本展示了使用WhatsApp應用發起“握手”的一種方法。

public void sendOtpIntentToWhatsApp() {
   // Send OTP_REQUESTED intent to both WA and WA Business App
   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
  */
  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
  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.
  Bundle extras = intentToWhatsApp.getExtras();
  if (extras == null) {
     extras = new Bundle();
  }
  extras.putParcelable("_ci_", pi);
  intentToWhatsApp.putExtras(extras);
  getApplicationContext().sendBroadcast(intentToWhatsApp);
}

錯誤訊號

如果您的訊息未通過WhatsApp的任意一項資格檢查，一鍵自動填寫按鈕將被替換為複製驗證碼按鈕。此外，還可能有裝置、WhatsApp應用設定阻止訊息通知。為協助調試，WhatsApp應用會通過傳遞com.whatsapp.OTP_ERROR意圖來顯示一些錯誤資訊。在這種情況下，您將收到錯誤密鑰和訊息，而不是使用者的單次密碼或驗證碼。

請注意，其中某些錯誤訊號只有在Android模擬器中運行WhatsApp應用時才會出現。

整合

錯誤訊號通過廣播意圖送達，因此必須運行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()); } } } ]]>

應用樣本

請訪問Github網站，參閱適用於Android平台的WhatsApp單次密碼 (OTP) 應用樣本。該應用樣本展示了如何通過 API 發送和接收單次密碼和驗證碼、如何整合一鍵自動填寫按鈕和複製驗證碼按鈕、如何建立模板以及如何啟動樣本伺服器。​