Скачать приложение
для разработчиков
прайс
СВЯЗАТЬСЯ
блог
СВЯЗАТЬСЯ
Связаться
Скачать приложение
для разработчиков
прайс
СВЯЗАТЬСЯ
блог
updated 04 Nov 2024
Wallet API для Android
Приложение Wallet позволяет провайдерам электронных карт отправлять пуш уведомления на выпущенные ими карты, установленные в приложении. Эта страница описывает все необходимые аспекты сервиса, которые требуется интегрировать в сервисы провайдеров, как для работы с платформой Google Android, так и с Huawei без установленных сервисов Google.
Регистрация устройства для получения пуш уведомлений
Приложение Wallet полностью поддерживает протокол Apple's для регистрации устройства с сервисом провайдера. Все команды протокола, типы и структуры данных поддержаны так, как описано в документе Apple APPLE WALLET WEB SERVICE REFERENCE

Для индикации того, что карта установлена в приложение Wallet, приложение Wallet заменяет в заголовке запроса оригинальную строку ApplePass с соответствующей строкой:
Authorization: WalletUnionPass aabbccddeeff11223344
Authorization: WalletUnionHMSPass aabbccddeeff11223344
Это единственное отличие от оригинальной срецификации Apple. Так что если ваш сервис уже работает с протоколом Apple Wallet, то вы легко сможете добавить поддержку для приложения Wallet для Android и Huawei.
Идентификация приложения
Для того, чтобы идентифицировать приложение Wallet в ваших вэб страницах выдачи карт, приложение передает уникальную строку в заголовке User-Agent при доступе к странице или при сканировании приложением QR кода.
WalletUnion/1.0 Passbook/1.0 (Linux; U; Android <version>; <manufacturer> <model>)
WalletUnionHMS/1.0 Passbook/1.0 (Linux; U; Android <version>; <manufacturer> <model>)
Passbook/1.0 добавлено для совместимости с сервиса провайдерами, кто еще не определяет запрос от приложения Wallet.

таким образом HTTP запрос содержит следующий заголовок User-Agent: 
User-Agent: WalletUnion/1.0 Passbook/1.0 (Linux; U; Android 14; samsung SM-A556E)
User-Agent: WalletUnionHMS/1.0 Passbook/1.0 (Linux; U; Android 12; HUAWEI MAO-LX9)
В запросе также присутствует дополнительный заголовок Accept-language, нацеленный помочь вам с определением языка, который использует приложение:
Accept-Language: zz;q=0.9
где zz установлено в текущий язык приложения, например en, ru, de и так далее.
Отправка пуш уведомлений в Wallet
Адрес сервиса и формат запроса
Для отправки запроса на сервис используйте следующие правила:

  • POST запрос на https://push.walletunion.com/send
  • HTTP заголовок должен содержать Authorization: <API Key>
  • HTTP заголовок должен содержать Content-type: application/json
  • Тело запроса должно включать требуемые данные
Любой сервис может отправить пуш сообщения на свои карты, установленные в приложении Wallet. Для отправки требуется включить в запрос API ключ. Чтобы получить свой ключ, заполните форму. Ключ выдается бесплатно для тестирования сервиса. Для коммерческого использования необходимо дополнительно приобрести соответствующую лицензию.
{ 
"passTypeIdentifier":"pass.your.passtype.id", 
"pushTokens":["eyKU4bqE...PMml5PJX848I","cA47ZTE...WJlHmId0Ib6uv",... ] ,
"hms":false // не обязательный параметр
}
{ 
"passTypeIdentifier":"pass.your.passtype.id", 
"pushTokens":["eyKU4bqE...PMml5PJX848I","cA47ZTE...WJlHmId0Ib6uv",... ] ,
"hms":true // обязательный параметр
}
API Ответ
В ответе на запрос сервис вернет один из вариантов ответа:

  • HTTP 200 и статус доставки как json в теле ответа
  • HTTP 400 на ошибку в переданных данных
  • HTTP 401 на ошибку авторизации
  • HTTP 403 Требуется лицензия для отправки пуш сообщений на passtypeid. Лицензию можно запросить в Личном Кабинете сервиса
  • HTTP 413 при превышении количества устройств в одном запроса на пуш
  • HTTP 429 при превышении лимита на скорость отправки запросов
В случае успешного запроса (HTTP 200), сервер вернет json структуру с пустым массивом проблемных токенов. 

{
"status":"OK",
"unknown_push_tokens":[ ],
"expired_push_tokens":[ ]
}
Если в запросе были токены, не ассоциированные с запрошенным passTypeIdentifier, или если Google FCM или Huawei HMS сервисы не приняли некоторые токены к доставке по любой причине, тогда ответ будет выглядеть:
{
"status":"ERROR",
"unknown_push_tokens":["ra9LE...ddm5hMP","bdH2OH...76jJuQ9YWn0T7k",...],
"expired_push_tokens":["f1G3hR..xeM5o","e41bJ2...gApIc","bdH2OH...76jJuQ9YWn0T7k"]
}
Наличие проблемных токенов в ответе означает, что или какие-то ваши карты не установлены на данном устройстве, или телефон не зарегистрировался на получение пуш уведомлений с сервисом, или пользователь отключил автоматическое обновление карт на устройстве. Вам не следует повторять запрос на такие токены до тех пор, пока устройство не зарегистрируется с сервисом и с вашей платформой.

Токены в ответе, находящиеся в массиве "expired_push_tokens" , считаются удаленными навсегда. Такие токены следует удалить из вашей базы устройств и более не пытаться отправлять на них запросы. Дополнительно, такие токены так же присутствуют в массиве "unknown_push_tokens" для совместимости с предыдущими версиями сервиса.
Если по какой-либо причине Google FCM или Huawei HMS не смогли принять запрос на отпраку пушей на устройства, ответ сервиса будет содержать следующие данные:
{
"status":"FCM_FAILED",
"unknown_push_tokens":["ra9LE...ddm5hMP","bdH2OH...76jJuQ9YWn0T7k",...],
"expired_push_tokens":[ ]
}
В такой ситуации все переданные в запросе устройства будут возвращены в ответе. Следует повторить попытку отправки позже.

Если в запросе слишком много токенов, то сервис вернет HTTP 413 со статусом: 

HTTP/1.1 413 Too many FCM pushTokens, max=50
HTTP/1.1 413 Too many HMS pushTokens, max=1000
В настоящее время сервис не ограничивает количество и скорость отправки запросов. Но в некоторых ситуациях сервис может временно применить ограничения на запросы. В таких случаях сервис вернет HTTP 429 с соответствующими пояснениями ограничений.: 

HTTP/1.1 429 Too many requests 
X-Rate-Limit-Limit: 3000 
X-Rate-Limit-Remaining: 100 
Retry-After: 30
Установка Wallet, загрузка карт, запуск Wallet
Приложение Wallet поддерживает автоматическую установку приложения если оно еще не установлено на телефоне. Так же поддерживается автоматическая загрузка карт после установки приложения. Если же приложение уже установлено, оно может загрузить карты по одному клику.

Ниже приведен искусственный пример простейшей веб странички, на которой по нажатию кнопки пользователь будет перенаправлен на Google Play или Huawei AppGallery для установки приложения. Карта будет импортирована автоматически после установки и запуска приложения.

Этот пример работает только с браузером Google Chrome!
<You can install your card by tapping the button "Add to Wallet"> 
<input type="submit" value="Add to Wallet" onclick="importInstallWallet(passURL);">

<You can launch Wallet app by tapping the button "Open Wallet"> 
<input type="submit" value="Open Wallet" onclick="launchWallet();">
<script>
/* !! Works only with Google Chrome browser !! */

/* 
* If Wallet is already installed, will automatically open Wallet and import pass
* If Wallet is not installed, will redirect user to the app's page
* After installing and opening the app, pass will import automatically
*/
function importInstallWallet(passurl) { 
var uri = encodeURIComponent(passurl); 
var fallback = "https://play.google.com/store/apps/details?id=com.walletunion.wallet&referrer=" + uri; 
var fullLink = "intent://import/" + uri + "#Intent;scheme=walletunion;package=com.walletunion.wallet;" 
+ "S.browser_fallback_url=" + fallback +";end"; 
window.location = fullLink;
}

/* 
* If Wallet is already installed, will automatically open Wallet
* If Wallet is not installed, will redirect user to the app's page
*/
function launchWallet() { 
var fallback = "https://play.google.com/store/apps/details?id=com.walletunion.wallet;" 
var fullLink = "intent://launch/#Intent;scheme=walletunion;package=com.walletunion.wallet;" 
+ "S.browser_fallback_url=" + fallback +";end";
windows.location = fullLink;
}
</script>
Этот пример работает только со встроенным браузером Huawei!
<You can install your card by tapping the button "Add to Wallet"> 
<input type="submit" value="Add to Wallet" onclick="importInstallWallet(passURL);">

<You can launch Wallet app by tapping the button "Open Wallet"> 
<input type="submit" value="Open Wallet" onclick="launchWallet();">
<script>
/* !! Works only with Huawei built-in browser !! */

/* 
* If Wallet is already installed, will automatically open Wallet and import pass
* If Wallet is not installed, will redirect user to the app's page
* After installing and opening the app, pass will import automatically
*/
function importInstallWallet(passurl) { 
var uri = encodeURIComponent(passurl); 
var fallback = encodeURIComponent('https://appgallery.cloud.huawei.com/appDetail?pkgName=com.walletunion.wallet&referrer=' + passurl);
var fullLink = 'intent://import/' + uri + '#Intent;scheme=walletunion;package=com.walletunion.wallet;'
         + 'S.browser_fallback_url=' + fallback + ';end';
window.location = fullLink;
}

/* 
* If Wallet is already installed, will automatically open Wallet and import pass
* If Wallet is not installed, will redirect user to the app's page
*/
function launchWallet() { 
var fallback = encodeURIComponent('https://appgallery.cloud.huawei.com/appDetail?pkgName=com.walletunion.wallet'); 
var fullLink = 'intent://launch/#Intent;scheme=walletunion;package=com.walletunion.wallet;'
+ 'S.browser_fallback_url=' + fallback +';end';
window.location = fullLink; 
}
</script>
Привязка Android приложения к карте
Приложение Wallet поддерживает связку карты с любым приложением на ваш выбор. Если приложение еще не установлено на устройстве, то заданный текст и соответствующая иконка из Google Market будет показана на обороте карты. при нажатии на иконку, пользователь будет перенаправлен на страничку установки приложения в Play Market. Если же приложение уже установлено, нажатие на иконку запустит приложение.

Чтобы разрешить данную возможность, добавьте json структуру верхнего уровня в ваш pass.json в файл архива pass.pkpass:

"associatedApps":[
{ 
"title":"My special app", "idGooglePlay":"com.mydomain.myapp"
}
]
Кнопки Add to Wallet
Для ваших веб страниц выдачи карт вы можете использовать соответствующие векторные кнопки. Они представляют из себя SVG картинки и доступны на многих языках. Если вы не нашли нужного вам языка, дайте нам знать.

Скачать приложение
удобным для вас способом