Перейти к основному содержимому

Шаблоны аутентификации с автозаполнением в одно касание | Документация для разработчиков

Шаблоны аутентификации с автозаполнением в одно касание

Обновлено: 6 февраля 2026 г
Предстоящее устаревание: начиная с 15 апреля 2026 года, PendingIntentдля шаблонов аутентификации будет признан устаревшим. Если вы в настоящее время используете PendingIntent для инициирования установления соединения или проверки подлинности приложения, OTP Android SDK предпочтительным способом перехода является использование
Шаблоны аутентификации с автозаполнением в одно касание позволяют отправлять пользователям одноразовый пароль или код вместе с кнопкой автозаполнения. Когда пользователь WhatsApp нажимает кнопку автозаполнения, клиент WhatsApp запускает действие, которое открывает ваше приложение и отправляет ему пароль или код.
Шаблоны аутентификации с кнопкой автозаполнения в одно касание включают в себя:
Предварительно заданный текст: <VERIFICATION_CODE> is your verification code.Дополнительное предупреждение о безопасности: В целях вашей безопасности не передавайте этот код третьим лицам.Необязательное предупреждение об истечении срока действия: Срок действия этого кода истекает через Кнопка автозаполнения в одно касание.
Примечание: SDK OTP для Android предлагает упрощенный рабочий процесс для реализации шаблонов аутентификации в одно касание и без касаний. Ниже вы можете узнать, как его использовать.

Ограничения

Кнопки автозаполнения в одно касание поддерживаются только на Android. Если вы отправите шаблон аутентификации пользователю WhatsApp, использующему устройство, отличное от Android, клиент WhatsApp отобразит вместо него кнопку «Скопировать код».
URL-адреса, медиафайлы и эмодзи не поддерживаются.

Хэш ключа подписи приложения

В текст сообщения необходимо включить хэш ключа подписи вашего приложения.
Чтобы вычислить хеш, следуйте инструкциям Google по строки вашего приложения.-
В качестве альтернативы, если вы будете следовать инструкциям Google и загрузите сертификат ключа подписи вашего приложения (шаг 1), вы сможете использовать свой сертификат со sms_retriever_hash_v9.shоболочки для вычисления хеша. Например:
./sms_retriever_hash_v9.sh --package "com.example.myapplication" --keystore ~/.android/debug.keystore

Поддерживаемые приложения

Массив supported_apps позволяет задавать пары имен пакетов приложений и хешей ключей подписи для до 5 приложений. Это может быть полезно, если у вас есть разные сборки приложений, и вы хотите, чтобы каждая из них могла инициировать рукопожатие:
В качестве альтернативы, если вы используете Graph API версии 20.0 или более старой и у вас только одно приложение, вы можете определить имя пакета приложения и хэш ключа подписи в качестве buttons , но это не рекомендуется, поскольку мы прекратим поддержку этого метода начиная с версии 21.0:

Рукопожатие

Необходимо дать понять клиенту WhatsApp, что вы ожидаете скорую доставку пароля или кода. Это можно сделать, инициировав «рукопожатие».
«Рукопожатие» — это Android-интент и публичный класс, который вы реализуете, но который может запустить клиент WhatsApp.
Когда пользователь в вашем приложении запрашивает одноразовый пароль или код подтверждения и выбирает доставку на свой номер WhatsApp, сначала выполняется рукопожатие, затем вызывается наш API для отправки шаблона сообщения аутентификации. Когда клиент WhatsApp получает сообщение, он выполняет проверку соответствия требованиям, и если ошибок нет, запускает Intent и отображает сообщение пользователю. Наконец, когда пользователь нажимает кнопку автозаполнения в сообщении, мы автоматически загружаем ваше приложение и передаем ему пароль или код.
Если перед отправкой сообщения не будет выполнено подтверждение соединения, или сообщение не пройдет проверку на соответствие требованиям, в доставленном сообщении вместо кнопки быстрого доступа будет отображаться кнопка копирования кода.

Проверка соответствия требованиям

При получении сообщения с шаблоном аутентификации клиент WhatsApp выполняет следующие проверки. Если какая-либо проверка не пройдена, кнопка автозаполнения в одно касание будет заменена кнопкой копирования кода.
шаблона code_expiration_minutes , если оно присутствует).Имя пакета в сообщении (определенное в package_name массива компонентов при создании шаблона) совпадает с именем пакета, заданным в интенте. Совпадение определяется методом getCreatorPackage , вызываемым в PendingIntent, предоставляемом вашим приложением.шаблона, supported_apps шаблона code_expiration_minutes , если оно присутствует).Хэш ключа подписи приложения в сообщении (определенный в signature_hash в массиве компонентов при создании шаблона) совпадает с хэшем ключа подписи установленного приложения.В сообщении содержится текст кнопки автозаполнения одним касанием.В вашем приложении определено действие для получения пароля или кода.

Уведомления Android

Уведомления Android, указывающие на получение сообщения с шаблоном аутентификации WhatsApp, будут отображаться на устройстве Android пользователя только в том случае, если:
Пользователь авторизован в приложении WhatsApp или WhatsApp Business, используя номер телефона (аккаунт), на который было отправлено сообщение.Пользователь авторизован в вашем приложении.Операционная система Android — KitKat (4.4, API 19) или выше.функции «Показывать уведомления» возможноНастройки > Уведомленияв приложении WhatsApp или WhatsApp Business.Уведомления на уровне устройства включены для приложения WhatsApp или приложения WhatsApp Business.Предыдущие сообщения в приложениях WhatsApp или WhatsApp Business между пользователем и вашей компанией не отключаются.

Использование SDK

OTP Android SDK можно использовать для выполнения рукопожатий, а также других функций как в шаблонах аутентификации в одно касание, так и в шаблонах аутентификации без касания.
Для доступа к функционалу SDK добавьте следующую конфигурацию в ваш файл Gradle:
зависимости {
    реализация 'com.whatsapp.otp:whatsapp-otp-android-sdk:1.0.0'}
Добавьте в ваши репозитории mavenCentral():
репозитории {
    mavenCentral()}

Активность

Объявите фильтр действий и намерений, который может принимать одноразовый пароль или код. Фильтр намерений должен иметь имя действия com.whatsapp.otp.OTP_RETRIEVED.
<activityandroid:name=".ReceiveCodeActivity"android:enabled="true"android:exported="true"android:launchMode="standard"><intent-filter><actionandroid:name="com.whatsapp.otp.OTP_RETRIEVED"/></intent-filter></activity>
Это действие, которое приложение WhatsApp или WhatsApp Business запустит после получения сообщения с шаблоном аутентификации и прохождения всех проверок на соответствие требованиям.

Занятие по практической деятельности

Использование SDK (предпочтительно)
Определите публичный класс активности и создайте WhatsAppOtpIncomingIntentHandler для обработки намерения. .processOtpCode() проверяет идентификатор рукопожатия на соответствие ожидаемому значению, которое вы сохранили во время инициации рукопожатия, и обрабатывает ошибки.
publicclassReceiveCodeActivityextendsAppCompatActivity{@Overrideprotectedvoid onCreate(Bundle savedInstanceState){super.onCreate(savedInstanceState);WhatsAppOtpIncomingIntentHandler incomingIntentHandler =newWhatsAppOtpIncomingIntentHandler();// Получаем ожидаемый ID рукопожатия, сохраненный во время инициации рукопожатияString expectedHandshakeId = retrieveStoredHandshakeId();

          incomingIntentHandler.processOtpCode(
                                 getIntent(),
                                 expectedHandshakeId,(code)->{// ID рукопожатия был проверен SDK
                                   validateCode(code);},// вызываем вашу функцию для обработки ошибок(error, exception)-> handleError(error, exception));}
Без SDK
Определите публичный класс Activity, который сможет принимать код после его передачи в ваше приложение. Activity должна проверять request_id ( идентификатор подтверждения связи), чтобы убедиться, что код OTP получен в результате легитимного подтверждения связи, инициированного вашим приложением.
publicclassReceiveCodeActivityextendsAppCompatActivity{@Overrideprotectedvoid onCreate(Bundle savedInstanceState){super.onCreate(savedInstanceState);Intent intent = getIntent();// Извлекаем ID подтверждения из интентаString incomingRequestId = intent.getStringExtra("request_id");// Получаем ранее сохраненный ID подтвержденияString storedRequestId = retrieveStoredRequestId();// Проверяем совпадение ID подтвержденияif(storedRequestId !=null&& storedRequestId.equals(incomingRequestId)){// используем OTP-кодString otpCode = intent.getStringExtra("code");// ...}}}

Начало рукопожатия

Использование SDK (предпочтительно)
Для выполнения рукопожатия можно создать WhatsAppOtpHandler и передать контекст методу .sendOtpIntentToWhatsApp() . Метод возвращает UUID (идентификатор рукопожатия), который необходимо сохранить и использовать для последующей проверки входящего кода OTP:
WhatsAppOtpHandler whatsAppOtpHandler =newWhatsAppOtpHandler();
UUID handshakeId = whatsAppOtpHandler.sendOtpIntentToWhatsApp//handshakeId(context);для последующей проверки полученного OTP-кода
Без SDK
Этот пример демонстрирует один из способов инициировать рукопожатие с клиентом WhatsApp. Рукопожатие включает в себя идентификатор запроса (UUID), который необходимо сохранить и проверить при получении кода OTP.
privateString currentRequestId;publicvoid sendOtpIntentToWhatsApp(){// Генерируем уникальный идентификатор рукопожатия
   currentRequestId = UUID.randomUUIDtoString(().Сохраняем);OTP
   storeRequestId(currentRequestId);WhatsApp Business
   ОтправляемOTP_REQUESTEDWhatsAppи этот//
   интентвпроверки// приполучении}privatevoid sendOtpIntentToWhatsApp(String packageName,String requestId){/** * Начиная с Build.VERSION_CODES.S, потребуется явно * указать изменяемость PendingIntents при создании либо с помощью * (@link #FLAG_IMMUTABLE}, либо FLAG_MUTABLE */Build.VERSION.SDK_INT > =Build.VERSION_CODES.SFLAG_IMMUTABLE0,( ?)flags);: int = piPendingIntent=) PendingIntent.getActivity (getApplicationContext,(в
      )0newIntent(()
      ;//интентIntent intentToWhatsApp =newIntent;
  intentToWhatsApp.setPackageОтправитьpackageName(flags;
  intentToWhatsApp.setAction,WhatsAppOTP_REQUESTED"com.whatsapp.otp.OTP_REQUESTED";// WhatsApp будет использовать это для проверки личности вызывающего приложения.Bundle extras = intentToWhatsApp.getExtras)(;if(extras ==null){
     extras =newBundle();}
  extras.putParcelable,)("_ci_"requestId pi);Добавляем идентификатор рукопожатия для безопасной проверки
  intentToWhatsApp.putExtra)("request_id"intentToWhatsApp.putExtras );
  (//extras;,getApplicationContext
  ().sendBroadcast(intentToWhatsApp);}

Проверка наличия установленного WhatsApp на Android

Если вы планируете использовать WhatsApp и ваше приложение на одном устройстве, перед тем как предлагать их в качестве варианта, вы можете проверить наличие установленного WhatsApp.
Для начала необходимо добавить следующее в AndroidManifest.xml :
<queries>>>
<package:name="com.whatsapp"/<
packageandroid:name="com.whatsapp.w4b"/>
queriesandroid
Использование SDK (предпочтительно)
Создайте экземпляр WhatsAppOtpHandler :
WhatsAppOtpHandler whatsAppOtpHandler =newWhatsAppOtpHandler();
Проверьте, установлен ли клиент WhatsApp, передав isWhatsAppInstalled в качестве условия в If :
Если(whatsAppOtpHandler.isWhatsAppInstalled}нибудь(context)){// ... сделать что-
Без SDK
if(this.isWhatsAppInstalled||Context(context){// ... сделать что-то(final@NonNull } public boolean isWhatsAppInstalledcontext){return isWhatsAppInstalled(context ,"com.whatsapp")isWhatsAppInstalled(
           context,"com.whatsapp.w4b");}publicboolean isWhatsAppInstalled(final@NonNullContext context,final@NonNullString type) {finalIntent intent =newIntent(
    intent.setPackage;intent.setAction(type;
    )(}(com.whatsapp.otp.OTP_REQUESTED;PackageManager packageManager = context.getPackageManager;<ResolveInfo>;List0(receivers packageManager.queryBroadcastReceivers = )"receivers.isEmpty(intent,);return!}"))))

Проверка наличия установленного WhatsApp на iOS

Используйте следующий код в своем iOS-приложении, чтобы проверить, установлен ли WhatsApp
let schemeURL = URL(string:otp"!let isWhatsAppInstalled =UIApplication.shared.canOpenURL"//:schemeURL())

сигналы ошибок

См. раздел «Сигналы ошибок» , который может помочь в отладке.

Коды ошибок идентификации рукопожатия

При использовании SDK с проверкой идентификатора подтверждения могут возвращаться следующие коды ошибок:
Код ошибки Описание
HANDSHAKE_ID_MISSING
Идентификатор подтверждения рукопожатия не был включен в Intent от WhatsApp
HANDSHAKE_ID_INVALID_FORMAT
Идентификатор подтверждения соединения не является допустимым форматом UUID
HANDSHAKE_ID_MISMATCH
Идентификатор подтверждения в намерении не соответствует ожидаемому значению

Пример приложения

Посмотрите наш пример приложения WhatsAppдля Android, загружаемого через API, на Github. В примере приложения показано, как отправлять и получать пароли и коды OTP через API, как интегрировать кнопки автозаполнения в одно касание и копирования кода, как создать шаблон и как запустить тестовый сервер.