本頁面由 Cloud Translation API 翻譯而成。

使用 WebOTP API 驗證網路上的電話號碼

協助透過簡訊接收動態密碼的使用者

Eiji Kitamura

什麼是 WebOTP API？

現今，世界各地大多數的使用者都有自己的行動裝置，而開發人員通常會使用電話號碼做為服務使用者的 ID。

驗證電話號碼的方法有很多種，但系統會隨機產生簡訊傳送的動態密碼是最常見的密碼之一。正在傳送這組驗證碼返回開發人員伺服器示範電話號碼的控制。

這個想法已用於許多情境中，目的是：

以電話號碼做為使用者的 ID。註冊新的帳戶時有些網站會要求提供電話號碼，而不是電子郵件地址，做為帳戶 ID
兩步驟驗證。網站會在登入時要求你輸入一次性驗證碼透過簡訊，以密碼或其他知識因素傳送安全性。
確認付款：使用者在付款時，要求透過簡訊傳送的一次性驗證碼，有助於驗證來電者的意圖。

目前的程序會造成使用者的困擾，尋找簡訊中的動態密碼訊息，複製並貼到表單中的關鍵使用者歷程中的轉換率。簡化記錄和我們長期以來的成就許多全球大型開發商表示希望建立網路廣告要求Android 提供與這項目標完全相同的 API。不過 iOS 版和 Safari。

WebOTP API 可讓您的應用程式接收要在您的應用程式網域中運作。這樣一來，你就能透過程式輔助方式透過簡訊取得動態密碼，方便使用者傳送訊息及驗證電話號碼。

實例觀摩

假設使用者想透過網站驗證電話號碼。網站傳送簡訊給使用者，使用者輸入動態密碼訊息，驗證電話號碼擁有權。

使用 WebOTP API 時，使用者只要輕觸一下就能輕鬆完成這些步驟，各 API 的運作方式收到簡訊時，會彈出底部功能表，並提示使用者驗證電話號碼。點選「驗證」後按鈕，瀏覽器就會將動態密碼貼到表單中使用者不必按下 [Continue] (繼續)，即可提交表單。

下圖說明整個程序。

歡迎親自體驗示範模式。不會要求手機號碼或傳送簡訊到您的裝置，但您可以從複製示範中顯示的文字，藉此在其他裝置上進行。這麼做很有效不論寄件者是誰使用 WebOTP API。

使用 Chrome 第 84 版前往 https://web-otp.glitch.me，或和日後發布的訊息
透過另一支手機傳送以下簡訊簡訊給您的手機。

Your OTP is: 123456.

@web-otp.glitch.me #12345

你有收到簡訊，但看到提示要在輸入區域輸入驗證碼嗎？這就是 WebOTP API 對使用者的運作方式。

WebOTP API 的使用包含三個部分：

加上適當註解的 <input> 標記
網頁應用程式中的 JavaScript
透過簡訊傳送格式化的訊息文字。

先來介紹 <input> 標記。

為 `<input>` 標記加上註解

WebOTP 本身運作時不會有 HTML 註解，但適用於跨瀏覽器相容性，我們強烈建議您將 autocomplete="one-time-code" 新增至輸入動態密碼的 <input> 標記。

這可讓 Safari 14 以上版本建議使用者自動填入 <input> ] 欄位輸入動態密碼 (即使簡訊不支援 WebOTP 時，仍會採用「設定簡訊格式」一節所述的格式)。

HTML

<form>
  <input autocomplete="one-time-code" required/>
  <input type="submit">
</form>

使用 WebOTP API

WebOTP 很簡單只要複製並貼上以下程式碼，工作。不管怎樣，我都會為你逐步說明情況。

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    const ac = new AbortController();
    const form = input.closest('form');
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.log(err);
    });
  });
}

特徵偵測

功能偵測與許多其他 API 相同。正在聆聽 DOMContentLoaded 事件會等待 DOM 樹狀結構準備查詢。

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    …
    const form = input.closest('form');
    …
  });
}

敬上

處理動態密碼

WebOTP API 本身就夠了。使用 navigator.credentials.get()敬上以取得動態密碼。WebOTP 會為該方法新增 otp 選項。僅有一個屬性：transport，其值必須是含 'sms' 字串的陣列。

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
    …

這會在收到簡訊時觸發瀏覽器的權限流程。如果權限為授予後，傳回的承諾使用 OTPCredential 物件就會解析。

取得的 OTPCredential 物件內容

{
  code: "123456" // Obtained OTP
  type: "otp"  // `type` is always "otp"
}

接著，將動態密碼值傳遞至 <input> 欄位。直接提交表單能排除要求使用者輕觸按鈕的步驟。

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.error(err);
    });
    …

正在取消訊息

如果使用者手動輸入動態密碼並提交表單，您可以取消透過 options 物件中的 AbortController 例項使用 get() 呼叫。

JavaScript

    …
    const ac = new AbortController();
    …
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    …
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
    …

設定簡訊格式

API 本身看起來應該夠簡單，但您必須完成以下事項請務必在使用前瞭解郵件必須晚於系統會呼叫 navigator.credentials.get()，且必須在裝置上接收這項資訊呼叫 get()。最後，訊息必須遵循下列規範格式設定：

訊息的開頭是 (選填) 使用者可理解的文字，其中包含 4 到 10 個字元由英數字元組成的字串，最後一行則包含至少一個數字做為網址和動態密碼
叫用 API 的網站網址的網域部分必須放在前面上傳者：@。
網址必須包含井字號 (「#」)，後面接著動態密碼。

例如：

Your OTP is: 123456.

@www.example.com #123456

以下舉出不良示例：

格式錯誤的簡訊文字範例	無法運作的原因
`Here is your code for @example.com #123456`	「`@`」應為最後一行的第一個字元。
`Your code for @example.com is #123456`	「`@`」應為最後一行的第一個字元。
`Your verification code is 123456` `@example.com\t#123456`	`@host` 至 `#code` 之間應該有一個空格。
`Your verification code is 123456` `@example.com` `#123456`	`@host` 至 `#code` 之間應該有一個空格。
`Your verification code is 123456` `@ftp://example.com #123456`	無法加入網址配置。
`Your verification code is 123456` `@https://example.com #123456`	無法加入網址配置。
`Your verification code is 123456` `@example.com:8080 #123456`	無法納入通訊埠。
`Your verification code is 123456` `@example.com/foobar #123456`	無法納入路徑。
`Your verification code is 123456` `@example .com #123456`	網域中沒有任何空白字元。
`Your verification code is 123456` `@domain-forbiden-chars-#%/:<>?@[] #123456`	網域中沒有任何禁用字元。
`@example.com #123456` `Mambo Jumbo`	預計最後一行的預計是 `@host` 和 `#code`。
`@example.com #123456` `App hash #oudf08lkjsdf834`	預計最後一行的預計是 `@host` 和 `#code`。
`Your verification code is 123456` `@example.com 123456`	缺少 `#`。
`Your verification code is 123456` `example.com #123456`	缺少 `@`。
`Hi mom, did you receive my last text`	缺少 `@` 和 `#`。

示範

根據示範操作，嘗試各種訊息訊息： https://web-otp.glitch.me

您也可以建立分支並建立版本： https://glitch.com/edit/#!/web-otp.

使用跨來源 iframe 的 WebOTP

通常用於輸入跨來源 iframe 的簡訊動態密碼特別是使用 3D Secure 時。使用共同支援的通用格式跨來源 iframe，WebOTP API 則會傳送繫結至巢狀來源的 OTP。例如：

使用者前往 shop.example 購買了一雙信用卡鞋。
輸入信用卡號碼後，整合付款服務供應商會顯示表單內顯示 bank.example 的表單，要求使用者驗證身分電話號碼，快速結帳。
「bank.example」會傳送含有動態密碼的簡訊給使用者，輸入 PIN 碼，藉此驗證身分。

如要從跨來源 iframe 中使用 WebOTP API，您必須執行下列兩項操作：

在簡訊文字中同時註解頂端頁框和 iframe 來源撰寫新的電子郵件訊息
設定權限政策，允許跨來源 iframe 接收動態密碼直接從使用者登入

，瞭解如何調查及移除這項存取權。

iframe 實際運作中的 WebOTP API。

您可以到這裡試用 https://web-otp-iframe-demo.stackblitz.io.

在簡訊中為繫結來源加上註解

從 iframe 內呼叫 WebOTP API 時，簡訊必須包含頂層頁框起點 (在 @ 開頭，後面加上 # 的動態密碼) 且 iframe 來源在最後一行前面加上 @。

Your verification code is 123456

@shop.example #123456 @bank.exmple

設定權限政策

如要在跨來源 iframe 中使用 WebOTP，嵌入器必須授予存取權透過 otp 憑證權限政策設定 API，避免發生非預期的情況行為一般來說，您可以透過兩種方式達成這個目標：

透過 HTTP 標頭：

Permissions-Policy: otp-credentials=(self "https://bank.example")

透過 iframe allow 屬性：

<iframe src="https://bank.example/…" allow="otp-credentials"></iframe>

查看進一步瞭解如何指定權限政策的範例。

注意：Chrome 目前僅支援從跨來源 iframe 呼叫 WebOTP API 呼叫其祖系鏈結中「不超過一個」個不重複的來源。在下列情況：

a.com -> b.com
a.com ->b.com ->b.com
a.com ->a.com ->b.com
a.com ->b.com ->c.com

，瞭解如何調查及移除這項存取權。支援在 b.com 中使用 WebOTP，但 c.com 不支援。請注意，由於缺乏需求，系統也無法支援以下情況以及複雜的使用者體驗

a.com ->b.com ->a.com (呼叫 WebOTP API)

在電腦上使用 WebOTP

在 Chrome 中，WebOTP 支援監聽其他裝置收到的簡訊，協助使用者在電腦上完成電話號碼驗證。

WebOTP API 的電腦。

使用者必須在兩個裝置中登入同一個 Google 帳戶，才能使用這項功能電腦版的 Chrome 和 Android Chrome。

所有開發人員都需要在電腦版網站上導入 WebOTP API。和行動版網站一樣這通常代表交易不會十分要求關聯語意

詳情請參閱在電腦上使用 WebOTP API 驗證電話號碼。

常見問題

我傳送的郵件格式正確，但對話方塊並未顯示。發生了什麼事？

測試 API 時，請留意下列幾點：

如果寄件人的聯絡人清單中有寄件人的電話號碼，則受限於基礎 SMS User Consent API 的設計，系統不會觸發 API。
如果您在 Android 裝置上使用工作資料夾，而 WebOTP 會無法運作，請嘗試改為在個人資料夾中安裝及使用 Chrome (也就是您接收 SMS 訊息的同一個設定檔)。

請檢查格式，確認簡訊格式是否正確。

這個 API 是否與其他瀏覽器相容？

Chromium 和 WebKit 同意簡訊格式和 Apple 宣布在 iOS 14 上支援 Safari 以及 macOS Big Sur雖然 Safari 不支援 WebOTP JavaScript API，預設使用 autocomplete=["one-time-code"] 為 input 元素加上註解鍵盤會自動建議輸入動態密碼，前提是簡訊符合規定格式。

使用簡訊進行驗證安全嗎？

雖然簡訊動態密碼很適合用來驗證首次輸入的電話號碼的，務必謹慎地透過簡訊驗證電話號碼重新驗證，因為電話號碼可能會遭電信業者入侵及回收。 WebOTP 是方便的重新驗證及復原機制，但服務並搭配其他因素，例如知識難題網路驗證 API 強化驗證機制

該到哪裡回報 Chrome 的實作錯誤？

您發現 Chrome 實作錯誤嗎？

回報錯誤： https://new.crbug.com. 盡可能附上最多細節、重現流程的簡單指示。將「元件」設為 Blink>WebOTP。

對這項功能有何幫助？

您是否打算使用 WebOTP API？你的公共支援團隊可協助我們優先功能，並向其他瀏覽器廠商說明支援這些功能的重要性。使用主題標記將推文傳送至 @ChromiumDev #WebOTP敬上，並說明你使用這項服務的位置和方式。

使用 WebOTP API 驗證網路上的電話號碼

什麼是 WebOTP API？

實例觀摩

為 <input> 標記加上註解

使用 WebOTP API

特徵偵測

處理動態密碼

正在取消訊息

設定簡訊格式

示範

使用跨來源 iframe 的 WebOTP

在簡訊中為繫結來源加上註解

設定權限政策

在電腦上使用 WebOTP

常見問題

我傳送的郵件格式正確，但對話方塊並未顯示。發生了什麼事？

這個 API 是否與其他瀏覽器相容？

使用簡訊進行驗證安全嗎？

該到哪裡回報 Chrome 的實作錯誤？

對這項功能有何幫助？

資源

為 `<input>` 標記加上註解