Разберём два сценария: человек входит по одноразовому коду и получает подтверждение бронирования. Для первого соберём письмо и поле ввода, для второго — HTML, логотип, PDF-билет, разметку Gmail и календарный файл. По ходу объясним, что выполняет ваш сервер, что делает почтовый клиент и как проверить каждую часть.
Начните со своей задачи: письмо с кодом, подтверждение с вложениями, карточка бронирования Gmail, промоакция или событие в календаре. Ниже идут веб-поле и WebOTP, Android и iPhone. Это разные интеграции: добавление одной не включает остальные.
Обновлено 12 ноября 2026 года. Добавлены сквозной пример письма, сборка .eml без отправки, разбор полей Gmail и жизненного цикла календарного приглашения.
Копирование, автозаполнение и проверка — три разные задачи
Распознавание находит код в сообщении. Автозаполнение предлагает или переносит его в нужное поле. Серверная проверка решает, подтверждает ли этот код конкретное действие. Удобная кнопка не заменяет ни связи с попыткой входа, ни проверки срока действия.
Сам OTP — одноразовый код, а не обязательно «второй фактор». Код для подтверждения адреса, входа без пароля и дополнительной проверки после пароля может выглядеть одинаково. В интерфейсе нужно объяснять цель действия, а в архитектуре — различать эти сценарии.
Что изменилось в Gmail — и чего это не обещает
В сентябре 2026 года профильные издания сообщили о кнопке копирования OTP в мобильном Gmail. Android Authority описывает кнопку прямо под темой письма во входящих. Наблюдения касаются Android и iOS. Это сообщение о развёртывании функции, а не опубликованный контракт для разработчиков.

Поэтому в спецификации продукта нельзя обещать: «В Gmail у всех появится Copy code». Распознавание зависит от письма и доступности функции. Не следует переносить наблюдение о списке писем на push-уведомление, веб-версию Gmail или любой другой почтовый клиент. Для собственного сервиса достаточно сделать письмо понятным без специальной кнопки.
Предлагаемый шаблон письма: тема «Код входа в Example», один хорошо заметный код, назначение действия, срок действия и пояснение, что делать, если человек не запрашивал вход. Рядом не нужны похожие шестизначные номера заказа, лишние рекламные блоки или код только в картинке. Добавьте текстовую часть MIME-письма. Реальный результат проверяйте в используемых клиентских приложениях. Это рекомендации по ясности, а не документированный способ принудительно включить кнопку Gmail.
Код входа в Example
482913
Вы запросили вход в аккаунт на example.com.
Код действует 5 минут. Не сообщайте его другим людям.
Если это были не вы, не подтверждайте вход.Пример иллюстративный: пять минут — выбранная политика сервиса, а не общий лимит Gmail. В реальном продукте срок письма должен совпадать с серверной политикой.
Summary Cards, Email Markup и OTP нельзя объединять в один API
Gmail умеет показывать и другие полезные сведения. Справка Google о Summary Cards перечисляет отслеживание заказов, события, поездки, счета и предложения. Показ зависит в том числе от настроек умных функций и наличия достаточных данных в письме. Сводная карточка — часть интерфейса почтового клиента.

| Механизм | Что делает | Что может контролировать отправитель |
|---|---|---|
| Распознавание OTP | Может выделить код и предложить копирование | Понятность письма. Публичного переключателя Copy code не подтверждено |
| Summary Cards | Сводит сведения о заказах, поездках и других событиях | Корректные и согласованные данные в письмах |
| Email Markup / Highlights | Описывает поддерживаемые сущности и действия | Разметку, аутентификацию отправителя и процедуру допуска |
| Gmail API | Даёт разрешённый доступ к данным почтового ящика | OAuth-интеграцию своего приложения и обработку разрешённых данных |
Gmail Email Markup использует Schema.org и поддерживаемые форматы JSON-LD и Microdata для сущностей вроде заказа, доставки и бронирования. Это не способ объявить произвольный объект OTP и получить гарантированное автозаполнение. Для запуска размеченных писем у Google есть регистрация отправителя и требования к качеству и аутентификации писем. Валидный JSON сам по себе не гарантирует специальный интерфейс у адресата.
В документированном ресурсе Gmail API Message поле snippet — короткий фрагмент текста. Его нельзя трактовать как готовый OTP или результат Summary Cards. Отдельный публичный метод получения распознанного Gmail кода или карточки в проверенной документации не найден. Классификационные метки Workspace также не означают, что API отдаёт OTP.
Собираем понятное письмо: от данных до HTML
Представим мастер-класс по керамике: Alex забронировал место на 21 ноября, с 10:00 до 12:00 по Праге. Письмо должно сразу ответить на четыре вопроса: подтверждено ли место, когда приходить, куда идти и где билет. Даже если Gmail не покажет карточку, а картинки не загрузятся, эти ответы должны остаться.
Содержание, которое увидит получатель в демонстрационном письме:
Booking WS-1042 confirmed
Hello, Alex Morgan.
Ceramics workshop
21 November 2026, 10:00–12:00 (Europe/Prague)
Example Studio
Example Street 12, 110 00 Prague, Prague, CZYour PDF ticket is attached.
Все имена, адреса, домены и бронирование в примерах вымышлены. Код письма на английском, чтобы один и тот же пример можно было повторить в каждой языковой версии статьи. Это Node.js-модуль для проекта с уже установленным Nodemailer; он создаёт локальный preview.eml, никому ничего не отправляя. Сохраните следующие два блока по порядку в email-demo.mjs.
import nodemailer from "nodemailer";
import { readFile, writeFile } from "node:fs/promises";
const booking = {
id: "WS-1042", name: "Alex Morgan", event: "Ceramics workshop",
start: "2026-11-21T10:00:00+01:00", end: "2026-11-21T12:00:00+01:00",
when: "21 November 2026, 10:00–12:00 (Europe/Prague)",
venue: "Example Studio", street: "Example Street 12",
city: "Prague", region: "Prague", postalCode: "110 00", country: "CZ"
};
const escapeHtml = value => String(value).replace(/[&<>"']/g,
c => ({"&":"&", "<":"<", ">":">", '"':""", "'":"'"})[c]);
const address = `${booking.street}, ${booking.postalCode} ${booking.city}, ${booking.region}, ${booking.country}`;
const text = `Booking ${booking.id} confirmed\n\nHello, ${booking.name}.\n${booking.event}\n${booking.when}\n${booking.venue}: ${address}\nYour PDF ticket is attached.`;
let html = `<!doctype html><html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
</head><body style="margin:0;padding:24px;background:#ffffff;color:#202020;font-family:Arial,sans-serif">
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td>
<img src="cid:brand-logo@example.com" width="160" height="48" alt="Example Studio" style="display:block;border:0">
<h1 style="font-size:24px;line-height:32px">Booking ${escapeHtml(booking.id)} confirmed</h1>
<p>Hello, ${escapeHtml(booking.name)}.</p>
<p><strong>${escapeHtml(booking.event)}</strong><br>${escapeHtml(booking.when)}</p>
<p>${escapeHtml(booking.venue)}<br>${escapeHtml(address)}</p>
<p>Your PDF ticket is attached.</p>
</td></tr></table></body></html>`;booking — единый источник данных для текста, HTML, Gmail и календаря. В рабочем сервисе это проверенное бронирование из базы; строку when формируют из даты и часового пояса, а не поддерживают вручную. escapeHtml превращает символы в имени вроде < в текст, чтобы имя не стало тегом. text — самостоятельная читаемая версия письма, которую клиент может выбрать вместо HTML.
| Элемент | Зачем он здесь | Что проверять |
|---|---|---|
h1, p, br, strong, a, ul, li | Обычный текст, иерархия и ссылки | Смысл остаётся без стилей; действие открывается обычной HTTPS-ссылкой. |
table, tr, td | Предсказуемая раскладка | У таблиц для оформления — role="presentation". Таблицы с данными сохраняют семантику. |
img | Логотип или иллюстрация | Заданы реальные пропорции, размеры и alt. Дата, цена и код не спрятаны в изображении. |
| Inline CSS | Критичные отступы, цвет и шрифт | Основное содержание не зависит от внешнего CSS, flex/grid или фонового изображения. |
script, iframe, form | Не использовать для обычного интерактивного письма | JSON-LD ниже — блок данных специального назначения, а не разрешение выполнять JavaScript. |
Это консервативная основа, а не универсальная сертификация тегов. Например, Gmail поддерживает часть <style> и media queries, но это не доказывает поддержку классическим Outlook. Справочник Gmail полезен для проверки конкретного CSS-свойства. Проверка результата — полученное письмо с отключёнными картинками, на узком экране и в тёмной теме.
Добавляем логотип и PDF: почему одного HTML недостаточно
В HTML выше cid:brand-logo@example.com — ссылка на часть самого письма. Nodemailer получает PNG с точно таким же cid и связывает их. PDF остаётся отдельным скачиваемым файлом. Добавьте второй блок; запустите node email-demo.mjs ./logo.png ./ticket.pdf, передав свой PNG размером 160×48 и тестовый PDF без персональных данных.
const [logoPath, ticketPath] = process.argv.slice(2);
if (!logoPath || !ticketPath) throw new Error("Pass a PNG logo and a PDF ticket");
const [logo, ticket] = await Promise.all([readFile(logoPath), readFile(ticketPath)]);
if (!logo.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10]))) {
throw new Error("Logo is not a PNG");
}
if (ticket.subarray(0, 5).toString() !== "%PDF-") throw new Error("Ticket is not a PDF");
const message = {
from: "Example Studio <booking@example.com>", to: "alex@example.com",
subject: `Booking ${booking.id} confirmed`, text, html,
attachments: [
{ filename: "logo.png", content: logo, contentType: "image/png",
cid: "brand-logo@example.com", contentDisposition: "inline" },
{ filename: `ticket-${booking.id}.pdf`, content: ticket,
contentType: "application/pdf", contentDisposition: "attachment" }
]
};
const previewTransport = nodemailer.createTransport({
streamTransport: true, buffer: true, newline: "windows"
});
const result = await previewTransport.sendMail(message);
await writeFile("preview.eml", result.message);Откройте preview.eml в почтовом клиенте как локальный файл: должны быть видны текст, логотип и PDF-вложение. Это проверка собранного сообщения, ещё не проверка доставки. Проверка сигнатур в примере ловит перепутанный тип файла, но не заменяет проверку содержимого PDF и соответствия билета получателю. Если чтение файла упало, письмо не собирается: фраза «билет приложен» не отправится без билета.
MIME — способ упаковать несколько частей в одно письмо. Одна подходящая структура выглядит так; библиотека создаёт разделители и кодирование сама:
multipart/mixed
├── multipart/alternative
│ ├── text/plain; charset=utf-8
│ └── multipart/related
│ ├── text/html; charset=utf-8
│ └── image/png; Content-ID: <brand-logo@example.com>
└── application/pdf; filename=ticket-WS-1042.pdfalternative предлагает две версии одного содержания; related связывает HTML с его картинкой; mixed добавляет самостоятельный документ. Менять расширение на .pdf недостаточно: важны байты и Content-Type. Считайте размер готового сообщения, поскольку base64 увеличивает размер файла примерно на треть. Для массовой отправки собирайте персональный билет для каждого получателя, а не общий BCC с чужими документами.
Здесь логотип находится внутри тела письма. Можно заменить CID публичной стабильной HTTPS-картинкой, если её публикация допустима, но клиент может блокировать и внешние, и встроенные изображения. Логотип рядом с промоакцией задаётся отдельным полем ниже. Аватар рядом с отправителем через BIMI относится к настройке домена и требованиям почтового провайдера; PNG в HTML не включает BIMI. Не публикуйте приватный PDF ради удобной ссылки. Параметры вложений Nodemailer и локальная сборка через stream transport описывают используемый здесь API.
Gmail-карточка бронирования: какие данные передать и куда
Получатель читает «мастер-класс, 21 ноября, 10:00». Разметка передаёт те же факты машинно: это подтверждённое бронирование WS-1042, его владелец — Alex, событие проходит по указанному адресу. Gmail может использовать их в поддерживаемом интерфейсе бронирований. Это не HTML-карточка, которую вы рисуете сами, и не команда автоматически добавить событие в календарь.

Вставьте следующий блок между первым и вторым блоком примера, до создания message. Он добавит JSON-LD в <head> письма; посетитель не должен видеть JSON как текст. Изменять JSON-LD сайта или передавать его отдельным JSON-файлом во вложении для этого не нужно.
function emailJsonLd(data) {
const json = JSON.stringify(data);
if (json === undefined) throw new Error("Missing structured data");
return '<script type="application/ld+json">' + json
.replace(/</g, "\\u003c")
.replace(/>/g, "\\u003e")
.replace(/&/g, "\\u0026")
.replace(/\u2028/g, "\\u2028")
.replace(/\u2029/g, "\\u2029") + '</script>';
}
const reservation = {
"@context": "http://schema.org", "@type": "EventReservation",
reservationNumber: booking.id,
reservationStatus: "http://schema.org/ReservationConfirmed",
underName: { "@type": "Person", name: booking.name },
reservationFor: {
"@type": "Event", name: booking.event,
startDate: booking.start, endDate: booking.end,
location: {
"@type": "Place", name: booking.venue,
address: {
"@type": "PostalAddress", streetAddress: booking.street,
addressLocality: booking.city, addressRegion: booking.region,
postalCode: booking.postalCode, addressCountry: booking.country
}
}
}
};
html = html.replace("</head>", emailJsonLd(reservation) + "</head>");reservationNumber связывает письмо с бронированием, underName называет владельца, reservationFor описывает событие. +01:00 фиксирует смещение для этой ноябрьской даты: без него «10:00» неоднозначно. В примере указан полный адрес, потому что Google требует его для этого типа. Если в базе есть только название города, сначала нужно получить точный адрес площадки. Заполнять обязательные поля догадками нельзя. Контракт EventReservation определяет состав полей.
Сериализация нужна не только ради удобства. Название события может содержать кавычки или буквальный </script>. JSON.stringify правильно оформляет JSON, а замена < на \u003c не даёт значению закрыть HTML-блок. После разбора JSON исходное название восстановится. " здесь не замена кавычке JSON: это испортит данные. Формат блока описан в документации JSON-LD для писем.
Проверка идёт в четыре шага: разберите JSON из итогового HTML; сравните номер, владельца, время и адрес с видимым письмом; проверьте HTML через Email Markup Tester; затем проверьте непосредственно полученное письмо. Google разрешает самотестирование при совпадении аккаунта отправителя и получателя, но SPF или DKIM всё равно требуется. Для отправки пользователям отдельно выполняется процедура регистрации. Поэтому успешный локальный .eml не означает, что карточка уже заработала у клиентов. Тестирование схем и регистрация — следующие этапы после сборки.
Promotions: как описать скидку, не перепутав её с OTP
Теперь другой сценарий: человек ещё не купил мастер-класс. Вы отправляете акцию «60 € → 45 €, код CLAY15, до 20 ноября». Аннотация позволяет передать изображение, предложение и срок для вкладки Promotions. Эти же условия должны быть написаны обычным текстом в промописьме; подписка и отписка остаются частью вашего рассылочного процесса.


Следующий объект относится к отдельному промописьму, а не к подтверждению выше. Используйте ту же функцию emailJsonLd. Все URL на example.com — обозначения для примера: замените их своими проверенными публичными HTTPS-ресурсами до отправки.
const promotion = [
{ "@context": "http://schema.org/", "@type": "Organization",
logo: "https://example.com/assets/logo.png" },
{ "@context": "http://schema.org/", "@type": "DiscountOffer",
description: "Save €15 on the ceramics workshop", discountCode: "CLAY15",
availabilityStarts: "2026-11-12T09:00:00+01:00",
availabilityEnds: "2026-11-20T23:59:00+01:00" },
{ "@context": "http://schema.org/", "@type": "PromotionCard",
image: "https://example.com/assets/workshop.jpg",
url: "https://example.com/offers/ceramics",
headline: "Ceramics workshop", price: "60", priceCurrency: "EUR",
discountValue: "15" }
];
// In a separate promotional email, before building its message object:
html = html.replace("</head>", emailJsonLd(promotion) + "</head>");Здесь price: "60" — исходная цена, а discountValue: "15" — сумма, которую вычитают: итог 45 €, не скидка 15%. CLAY15 должен реально приниматься вашим checkout. availabilityEnds должен совпадать с окончанием акции на сервере. Для PromotionCard нужны картинка PNG/JPEG и целевая ссылка; у картинки — поддерживаемые пропорции 4:5, 1:1 или 1.91:1. CID-картинку из письма сюда не подставляют: сервису нужен доступный URL. Даже корректная аннотация не управляет сортировкой во вкладки и не гарантирует показ. Механизм Promotions и значения полей описывают именно это представление.

event.ics: сначала выберите импорт или приглашение
Для купленного мастер-класса обычно достаточно кнопки «Добавить в календарь» или файла, который человек импортирует. Это копия события у получателя. Если время позже изменится в вашей базе, такая копия не обязана обновиться. Если нужны ответы «Приму / Отклоню», перенос и отмена, нужен полноценный обмен приглашениями и обработка ответов, а не только другое имя файла.
Так выглядит минимальный файл для ручного импорта нашего события. DTSTART:20261121T090000Z — 09:00 UTC, то есть 10:00 в Праге в эту дату. DTEND — конец события. UID задаёт его постоянную идентичность. DTSTAMP — время формирования данных, не время начала мастер-класса.
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Studio//Booking//EN
CALSCALE:GREGORIAN
BEGIN:VEVENT
UID:booking-WS-1042@example.com
DTSTAMP:20261112T120000Z
DTSTART:20261121T090000Z
DTEND:20261121T110000Z
SUMMARY:Ceramics workshop
LOCATION:Example Studio\, Example Street 12\, Prague
DESCRIPTION:Booking WS-1042\nBring your PDF ticket.
END:VEVENT
END:VCALENDARВ файле нужны окончания строк CRLF и завершающий CRLF. Запятые, точки с запятой, обратные косые черты и переносы внутри текстовых значений экранируются. Длинные строки переносятся по байтам UTF-8, поэтому украинский текст нельзя обрезать обычным slice(0, 75). Добавьте этот код после создания message, до вызова previewTransport.sendMail:
const escapeIcsText = value => String(value).replace(/\\/g, "\\\\")
.replace(/;/g, "\\;").replace(/,/g, "\\,").replace(/\r\n|\r|\n/g, "\\n");
function foldIcsLine(line) {
let result = "", bytes = 0;
for (const character of line) {
const length = Buffer.byteLength(character, "utf8");
if (bytes + length > 75) { result += "\r\n "; bytes = 1; }
result += character; bytes += length;
}
return result;
}
const utc = value => new Date(value).toISOString()
.replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
const calendar = [
"BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//Example Studio//Booking//EN",
"CALSCALE:GREGORIAN", "BEGIN:VEVENT", `UID:booking-${booking.id}@example.com`,
`DTSTAMP:${utc(new Date())}`, `DTSTART:${utc(booking.start)}`, `DTEND:${utc(booking.end)}`,
`SUMMARY:${escapeIcsText(booking.event)}`,
`LOCATION:${escapeIcsText(booking.venue + ", " + address)}`,
`DESCRIPTION:${escapeIcsText("Booking " + booking.id + "\nBring your PDF ticket.")}`,
"END:VEVENT", "END:VCALENDAR"
].map(foldIcsLine).join("\r\n") + "\r\n";
message.attachments.push({ filename: "event.ics", content: Buffer.from(calendar),
contentType: "text/calendar; charset=utf-8", contentDisposition: "attachment" });Префикс Z означает UTC. Для реального бронирования храните IANA-зону, например Europe/Prague, и вычисляйте смещение для даты события: летом здесь будет +02:00, а не +01:00. Не используйте часовой пояс сервера. Проверяйте, что конец позже начала; несуществующее время при переходе на летний режим требует явного решения. Для события на весь день используют VALUE=DATE; окончание 22 ноября означает, что последнее включённое число — 21 ноября. Правила данных и строк задаёт iCalendar.
Для настоящего приглашения к тем же данным события добавляются поля ниже. Это только изменения, а не полный файл; многоточие обозначает остальные строки. Организатор и адресат должны быть реальными участниками обмена. PARTSTAT=NEEDS-ACTION означает «ответа ещё нет»; ставить ACCEPTED за человека нельзя.
METHOD:REQUEST
...
UID:booking-WS-1042@example.com
SEQUENCE:0
ORGANIZER:mailto:events@example.com
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:mailto:alex@example.comВнутри календаря нужен METHOD:REQUEST, а у MIME-части — Content-Type: text/calendar; charset=utf-8; method=REQUEST. В Nodemailer для такого письма есть icalEvent: { method: "REQUEST", content: requestCalendar }; этот путь используйте вместо обычного календарного вложения и держите приглашение простым, без дополнительных PDF и картинок, мешающих некоторым клиентам распознать его. Сам requestCalendar должен содержать полный корректный календарь. API Nodemailer упаковывает данные, но не создаёт систему планирования.
| Действие | Что отправить | Что хранить на сервере |
|---|---|---|
| Первое приглашение | REQUEST, UID booking-WS-1042@example.com, SEQUENCE:0 | Организатор, участник, время и текущая версия. |
| Перенос на 11:00 | REQUEST, тот же UID, SEQUENCE:1, новые DTSTART/DTEND и DTSTAMP | Версию увеличивают при изменении; повтор доставки не создаёт новую версию. |
| Отмена после переноса | CANCEL, тот же UID, SEQUENCE:2, STATUS:CANCELLED | Отмену и адресатов; MIME method тоже CANCEL. |
| Ответ участника | REPLY, тот же UID, соответствующая версия и PARTSTAT участника | Проверить отправителя и участника, актуальность события; затем обновить статус ответа. |
Соответствие MIME-метода содержимому файла описывает iMIP, RFC 6047; переносы, отмены и ответы — iTIP, RFC 5546. Не доверяйте присланному ATTENDEE как доказательству личности. Даже с постоянным UID нужно отдельно проверить повторный импорт, перенос и отмену в целевых календарях: поведение клиента не следует из одного успешного разбора файла.
Как понять, где сломалось письмо
| Симптом | Проверка | Исправление |
|---|---|---|
| Нет логотипа | В исходнике письма найти src="cid:…" и соответствующий Content-ID. Затем включить картинки. | Исправить несовпадение CID или упаковку related; сохранить текстовый бренд и alt. |
| Нет билета, но письмо обещает вложение | Проверить генерацию PDF и application/pdf в полученном MIME. | Собирать сообщение после успешной генерации; не отправлять ложное подтверждение вложения. |
| Нет Gmail-карточки | Проверить сохранность JSON-LD после провайдера, обязательные поля и допуск отправителя. | Исправить конкретный слой; не пытаться лечить это размером шрифта. |
| Событие на час раньше | Сравнить исходную дату, IANA-зону, смещение и DTSTART. | Вычислять UTC для даты экскурсии; согласовать HTML, текст и ICS. |
| При переносе появился дубль | Сравнить UID первого письма и обновления. | Хранить UID; обновлять версию события, а не генерировать новую идентичность. |
Сначала проверьте локальный .eml. Затем разрешённую тестовую отправку через рабочий провайдер: он может изменить HTML, ссылки или MIME. В Gmail, Apple Mail и используемых версиях Outlook проверьте обычный вид, тёмную тему, отключённые картинки, скачивание PDF и импорт ICS. Для RSVP дополнительно проведите полный цикл: приглашение → ответ → перенос → отмена. Записывайте клиент, версию и результат, а не одно общее «email работает».
Что выбрать для своего продукта
| Сценарий | Основной путь | Граница возможностей |
|---|---|---|
| Сайт, свой SMS-отправитель | Семантика поля + доменная привязка. WebOTP там, где поддерживается | Не чтение всех SMS и не доступ к письмам |
| Android, можно менять SMS | SMS Retriever API | Google Play services, формат сообщения и хеш приложения |
| Android, нельзя добавить хеш | SMS User Consent API, если сценарий соответствует условиям | Согласие на одно сообщение, ограничения отбора и времени ожидания |
| iPhone-приложение | Поле oneTimeCode и системный AutoFill | Распознаванием и показом подсказки управляет ОС |
| Код приходит по email | Понятное письмо + корректное поле + доступные системные подсказки | WebOTP не является API чтения email |
| Помощник для чужих сайтов и приложений | Разрешённые платформенные интеграции с проверкой назначения | Отдельный продукт с доступом к чувствительным данным |
Таблица описывает направления интеграции, а не гарантии по бренду телефона. Например, SMS Retriever относится к Google Play services: само наличие Android на устройстве не доказывает доступность этого механизма. Для устройств без нужных сервисов сначала нужно проверить официально поддерживаемый путь конкретной платформы.
Сайт: сначала правильное поле, затем WebOTP
Для числового кода используйте текстовое поле с цифровой клавиатурой. type="number" не подходит: код — идентификатор, а не число для вычислений. Начальные нули должны сохраняться. Рекомендации web.dev по OTP-формам объясняют сочетание inputmode и autocomplete="one-time-code".
<form id="verify-form" action="/auth/verify" method="post">
<label for="otp">Код из сообщения</label>
<p id="otp-hint">Введите 6 цифр. Начальные нули важны.</p>
<input id="otp" name="code" type="text"
inputmode="numeric" autocomplete="one-time-code"
pattern="[0-9]{6}" maxlength="6" required
aria-describedby="otp-hint otp-status">
<p id="otp-status" role="status"></p>
<button type="submit">Подтвердить</button>
</form>Шесть цифр здесь — явный контракт примера. Для буквенно-цифровых кодов потребуется другое ограничение и другая клавиатура. Маршрут /auth/verify условный: реализация сервера, защита запроса и привязка к попытке входа в этот фрагмент не включены.
Один настоящий input обычно проще для вставки, редактирования, AutoFill и скринридера, чем шесть независимых полей. Если дизайн требует шесть ячеек, это не отменяет полноценного ввода всего кода, корректного порядка фокуса и доступного имени. Не запрещайте вставку и не заставляйте перепечатывать цифры.
WebOTP в документации Chrome получает специально оформленное SMS, связанное с доменом. Механизм требует безопасного контекста и поддержки браузера. Safari может предлагать системный AutoFill для подходящих сообщений, не реализуя тот же JavaScript API. Поэтому проверяйте возможность, а не название ОС.
Код для входа в Example: 004291
@example.com #004291В последней строке — точный домен без схемы и пути и код с префиксом #. Для встраиваемых фреймов есть отдельные правила формата и Permissions Policy. Их нужно сверить с документацией WebOTP. Этот пример относится к обычной странице верхнего уровня.
const form = document.querySelector("#verify-form");
const input = document.querySelector("#otp");
const status = document.querySelector("#otp-status");
if (form && input && status && "OTPCredential" in window) {
const controller = new AbortController();
const stop = () => controller.abort();
form.addEventListener("submit", stop, { once: true });
input.addEventListener("input", stop, { once: true });
window.addEventListener("pagehide", stop, { once: true });
const timer = window.setTimeout(stop, 60_000);
navigator.credentials.get({
otp: { transport: ["sms"] },
signal: controller.signal
}).then(credential => {
if (!controller.signal.aborted && credential?.code && !input.value) {
input.value = credential.code;
input.dispatchEvent(new Event("input", { bubbles: true }));
status.textContent = "Код подставлен. Проверьте и подтвердите вход.";
}
}).catch(error => {
if (error.name !== "AbortError") {
status.textContent = "Введите код из сообщения вручную.";
}
}).finally(() => {
window.clearTimeout(timer);
form.removeEventListener("submit", stop);
input.removeEventListener("input", stop);
window.removeEventListener("pagehide", stop);
});
}Слушатель запускают до отправки ожидаемого SMS. В реальном потоке старт нужно согласовать с запросом к серверу. Пример отменяет ожидание при ручном вводе, отправке формы и уходе со страницы, не перезаписывает введённый код и не отправляет форму сам. Ожидание 60 секунд — настройка интерфейса, не срок жизни OTP. При отсутствии API, отказе пользователя или тайм-ауте доступен тот же ручной ввод. В компоненте SPA дополнительно отменяйте ожидание при размонтировании.
Android: Retriever, User Consent и AutofillService решают разные задачи
Практическая последовательность для Retriever: сервер создаёт попытку подтверждения; приложение запускает ожидание; после успешного старта запрашивает отправку SMS; сервер отправляет текст с кодом и хешем приложения; receiver получает результат; приложение передаёт код вместе с попыткой на сервер. На каждом шаге есть собственная ошибка. Например, неправильный release-хеш ломает получение сообщения приложением, но не доставку SMS на телефон — поэтому «SMS пришло» ещё не доказывает работу Retriever.
SMS Retriever API связывает сообщение с приложением через хеш. Команда согласует формат SMS с сервером, запускает ожидание до отправки и проверяет сообщение после получения. Это позволяет реализовать подтверждение без общего разрешения на чтение SMS.
Клиентские точки входа — SmsRetriever.getClient(context).startSmsRetriever() и startSmsUserConsent(senderAddress). Справочник SmsRetrieverClient описывает SMS_RETRIEVED_ACTION, статусы и защиту receiver разрешением SEND_PERMISSION. Успешный запуск ожидания ещё не означает, что сообщение получено. Согласие разбирают отдельно от результата доставки.
Внедрение требует зависимости Google Play services, корректного receiver, обработки успеха и тайм-аута. Хеш должен соответствовать идентификатору пакета и сертификату подписи: рабочая debug-сборка не доказывает работоспособность релиза из магазина. Передавайте полученный код в серверную проверку конкретной попытки, а не считайте получение SMS успешным входом.
Если добавить хеш нельзя, изучите SMS User Consent API. Пользователь разрешает передать приложению текст одного сообщения. Это существенное дополнение к упрощённому правилу «чужое SMS — только системная подсказка», но не разрешение собирать произвольные сообщения.

У User Consent есть условия отбора: ожидается буквенно-цифровой код длиной 4–10 символов хотя бы с одной цифрой. Отправитель не должен находиться в контактах. Документация описывает пятиминутное окно ожидания. Это параметры работы API, а не обязательные длина и срок жизни вашего OTP. Отмена согласия должна оставлять возможность ввести код вручную.
AutofillService — роль отдельного поставщика автозаполнения, например менеджера паролей, который пользователь включает в системе. Для обычного приложения, принимающего собственный код, это обычно другой уровень задачи. SMS Code Autofill API также относится к сценарию поставщика автозаполнения. Его нельзя считать разрешением для любого приложения перехватывать SMS.
Чтение уведомлений — ненадёжная основа для универсального сборщика кодов. В Android 15 содержимое уведомлений с обнаруженным OTP скрывается от недоверенных NotificationListenerService. Наличие пользовательского доступа к уведомлениям не отменяет это ограничение. Не проектируйте продукт вокруг обхода защиты.
iPhone: пометьте поле, распознавание оставьте системе
Email-коды умеют подставляться и без уведомлений сторонних приложений. В перечне функций iOS 17 Apple описывает AutoFill из Mail в Safari. Один и тот же ящик, открытый в Apple Mail и в приложении Gmail, не означает одинаковый путь распознавания. Для своего письма проверяйте конкретный клиент, настройки и поле назначения.
В официальном перечне функций iOS 26 Apple указывает Verification Code AutoFill from Notifications: коды могут подставляться из уведомлений приложений. Это системная возможность, а не API, позволяющий вашему приложению прочитать уведомления Gmail или любого мессенджера.
Для UIKit применяется UITextContentType.oneTimeCode, в SwiftUI — соответствующий модификатор поля:
TextField("Код подтверждения", text: $code)
.textContentType(.oneTimeCode)
.keyboardType(.numberPad)Параметр клавиатуры подходит только числовому коду. Доступность нужной подсказки зависит от распознанного сообщения, настроек и состояния устройства. Для SMS своего сервиса Apple описывает доменную привязку. Для приложения также учитываются связанные домены. Веб-поле с autocomplete="one-time-code" и нативное oneTimeCode выражают назначение ввода, но не гарантируют подсказку из каждого источника.
Отдельно проверяйте настройки уведомлений и скрытых превью. Если код не попал в доступное системе содержимое, нельзя рассчитывать, что функция его «достанет» из закрытого ящика. У приложения не появляется право читать соседние уведомления. TOTP из менеджера паролей — ещё один отдельный источник, его не следует смешивать с кодом, доставленным письмом.
Универсальный помощник — отдельный продукт
Улучшить свой checkout и построить помощника для любых сайтов — разные по масштабу проекты. Во втором случае сначала нужно определить, где он работает: расширение браузера, выбранный поставщик автозаполнения Android, почтовый клиент или разрешённое расширение платформы. Сайт не может сам превратиться в системный менеджер кодов на всём телефоне.
Gmail API с OAuth может дать приложению разрешённый доступ к содержимому писем. Но это доступ к данным ящика, а не узкий запрос «выдай ожидаемый код». В списке OAuth scopes Gmail чтение почты относится к restricted scopes. Требования к проверке приложения и, в применимых случаях, оценке безопасности нужно изучить до реализации. Для собственного OTP-экрана запрашивать доступ ко всему ящику обычно несоразмерно задаче.
Для другого почтового провайдера требуется его поддерживаемая интеграция и согласие пользователя. Нельзя обещать одинаковую работу с любым клиентом лишь потому, что оба показывают push. Публичного универсального интерфейса «все OTP со всех каналов» в рассмотренных платформах нет.
Если такой продукт всё же оправдан, связывайте найденное сообщение с конкретным запросом: аккаунтом, точным доменом или проверенной идентичностью приложения, назначением действия и временным окном. Совпадение имени отправителя, текста темы и последних шести цифр недостаточно. При неоднозначности не угадывайте: покажите контекст человеку или откажитесь от автоматического переноса. Подтверждение адреса, вход и перевод средств нельзя объединять только по одинаковому формату кода.
Что должно происходить после подстановки
Пример: пользователь запросил код A, нажал «Отправить ещё раз» и получил B. Если политика сервиса отменяет предыдущий код, A должен отклоняться, даже когда он пришёл позже и AutoFill подставил его первым. Сервер связывает проверку с идентификатором попытки, адресатом и назначением; проверяет срок, лимит попыток и одноразовое использование. Проверку кода и пометку «использован» выполняют атомарно, иначе два параллельных запроса могут принять один OTP дважды. Подстановка в поле меняет только интерфейс — сессию создаёт сервер после успешной проверки.
Сервер хранит состояние попытки: кому, для чего и когда выдан код, когда истекает, сколько было проверок и использован ли он. Проверка должна учитывать этот контекст, ограничивать перебор и повторную отправку, а успешное использование — атомарно погашать код. Политику старого кода после повторной отправки определите заранее и отразите в интерфейсе. Установленный таймер на экране не заменяет серверный срок.
Не записывайте OTP, содержимое письма или SMS в аналитику, консоль и тексты ошибок. Измерять можно попытки, задержку доставки, частоту повторной отправки и результат проверки без самих секретов. Различайте «код предложен», «поле заполнено» и «сервер подтвердил действие»: это разные события, а не один показатель успешного входа.
Интерфейс должен сохранять введённое при временной ошибке сети, объяснять истечение срока, позволять исправить адрес или номер и повторно отправить сообщение после понятного ограничения. Не очищайте поле при каждой неудаче и не объявляйте человеку «неверный код», если запрос вообще не дошёл до сервера. Автоматическая подстановка не должна перекрывать ручную вставку или неожиданно менять уже введённые цифры.
Проверка перед выпуском
| Ситуация | Ожидаемый результат |
|---|---|
| Код начинается с нулей | Нули сохранены при вводе, вставке и отправке |
| Сообщение пришло до запуска ожидания | Пользователь может ввести код. Интерфейс не зависает |
| Другой домен, аккаунт или назначение | Автоматическая передача не производится по одному совпадению цифр |
| Пользователь отказал в доступе | Тот же сценарий можно завершить вручную |
| Повторная отправка и старый код | Работает явно заданная серверная политика |
| Ручной ввод во время ожидания | Поздний AutoFill не перезаписывает введённое |
| Отказ сети, истечение срока, повторное использование | Понятные разные состояния и корректная серверная проверка |
| Клавиатура, скринридер, увеличенный текст | Поле имеет имя, ошибки связаны с ним, фокус не скачет |
| Release-подпись Android и целевые устройства | Проверена реальная интеграция, а не только debug-сборка |
Матрица нужна по каналам и реализациям: SMS своего сервиса, email, поддерживаемый WebOTP-браузер, Safari, целевые Android с нужными сервисами, iPhone с подходящей версией ОС. Отдельно проверяются несколько одновременных попыток, изменение аккаунта, уход со страницы и отсутствие уведомления. Утверждение «работает на iOS» не заменяет запись версии, настроек и проверенного сценария.
Скилл для разработки email-писем
По результатам этого исследования мы создали отдельный скилл Email Development для Codex и Claude Code. Он помогает создавать и улучшать письма: от темы и текстовой версии до HTML-шаблона, OTP, структурированной разметки Gmail и проверки в почтовых клиентах.
Скилл изучает существующие шаблоны, данные и провайдера отправки. Для кодов подтверждения он учитывает читаемость письма, срок действия, начальные нули, связь с попыткой входа и реальные ограничения AutoFill. Для заказов и бронирований помогает выбрать поддерживаемую разметку и проверить условия допуска Gmail. Он не обещает принудительно включить Copy code или получить доступ к чужой почте.
Установка в Codex:
$skill-installer install https://github.com/wladislaw353/agent-skills/tree/main/skills/email-developmentДля явного вызова используйте $email-development. В инструкции для Claude Code описана установка коллекции и её обновление. После установки плагина используйте /agent-skills:email-development, при ручной установке папки в ~/.claude/skills/ — /email-development.
Пример задачи: «Проанализируй наши письма с кодами подтверждения. Улучши HTML и текстовую версию, проверь доступность, совместимость и возможности Gmail. Подготовь результат для проверки». Скилл помогает с анализом и реализацией, отправка писем и изменение настроек домена требуют отдельного поручения.
Расширенный скилл также включает чек-лист совместимости тегов и CSS, проверку MIME-вложений, различия между логотипом в письме, Promotions и BIMI, безопасную генерацию JSON-LD и жизненный цикл приглашений event.ics. Проверки отделяют подтверждённый результат от возможностей, которые ещё нужно испытать в реальном почтовом клиенте.
