Appareils

Enregistrer un appareil

Votre serveur enregistre le jeton reçu par votre application avec PUT /v1/push/devices. L'appel est un upsert sur l'application, le jeton et le mode : l'appeler à chaque lancement de l'application est sans problème.

Le corps contient app_id, token (jusqu'à 512 caractères parmi les lettres, les chiffres, _, :, . et -), platform (ios ou android; un navigateur s’enregistre avec web et subscription au lieu du jeton, comme le montre la page Web push), user_id (votre propre identifiant de la personne, jusqu'à 255 caractères) et, pour iOS, apns_environment : sandbox pour les versions de développement et production pour les autres. Un jeton ne fonctionne que dans l'environnement pour lequel sa version a été signée. Ajoutez encryption_public_key, la clé publique que le paquet push de HonkIO a créée sur l'appareil, pour que honkio chiffre ses notifications : une nouvelle clé remplace celle enregistrée. Un nouvel enregistrement du même jeton sans le champ conserve sa clé, mais un nouveau jeton (après un renouvellement du jeton APNs ou FCM) est un nouvel appareil, sans clé si elle ne l'accompagne pas : envoyez donc la clé avec chaque jeton que vous enregistrez. Les paquets de HonkIO donnent la clé à votre application en même temps que le jeton. Seul un null explicite la retire; les notifications de cet appareil partent alors en clair ou, pour une application qui exige le chiffrement, il n'en reçoit plus (ENCRYPTION_KEY_MISSING) jusqu'à ce qu'il enregistre de nouveau une clé. Un appareil porte encryption_key_id, jamais la clé. Un navigateur ne prend pas de encryption_public_key : le web push le protège déjà (RFC 8291).

Enregistrer un appareil ou un navigateur demande le w de la permission push_devices, et retirer son d ; lister les appareils demande push r, et envoyer push w. Une clé pour le serveur qui ne fait qu'enregistrer et retirer des appareils peut ne détenir que push_devices. En OAuth, la portée push:devices l'accorde ; push:send ne l'accorde pas.

// Call this from your backend when the app reports its token.
const { data: device, error } = await honkio.push.devices.register({
  appId: 'APP_ID',
  token: 'DEVICE_TOKEN',
  platform: 'ios', // or 'android'
  userId: 'user_1042', // your own identifier for this person
  apnsEnvironment: 'production', // iOS only: 'sandbox' for development builds
  encryptionPublicKey: 'DEVICE_PUBLIC_KEY', // the key the HonkIO push package made on the device
})
if (error) throw new Error(error.message)
console.log(device.id, device.active, device.encryption_key_id)

from honkio import Honkio

client = Honkio()  # reads HONKIO_API_KEY

# Call this from your backend when the app reports its token.
device = client.push.devices.register(
    app_id="APP_ID",
    token="DEVICE_TOKEN",
    platform="ios",  # or "android"
    user_id="user_1042",  # your own identifier for this person
    apns_environment="production",  # iOS only: "sandbox" for development builds
    encryption_public_key="DEVICE_PUBLIC_KEY",  # the key the HonkIO push package made on the device
)
print(device["id"], device["active"], device["encryption_key_id"])

<?php

use Honkio\Honkio;

$honkio = new Honkio(); // reads HONKIO_API_KEY

// Call this from your backend when the app reports its token.
$device = $honkio->push->devices->register([
    'app_id' => 'APP_ID',
    'token' => 'DEVICE_TOKEN',
    'platform' => 'ios', // or 'android'
    'user_id' => 'user_1042', // your own identifier for this person
    'apns_environment' => 'production', // iOS only: 'sandbox' for development builds
    'encryption_public_key' => 'DEVICE_PUBLIC_KEY', // the key the HonkIO push package made on the device
]);
echo $device['id'], ' ', $device['active'] ? 'active' : 'inactive', ' ', $device['encryption_key_id'] ?? 'no key', PHP_EOL;

curl -X PUT https://api.honkio.ca/v1/push/devices \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "APP_ID",
    "token": "test_accept",
    "platform": "ios",
    "user_id": "user_1042",
    "apns_environment": "sandbox",
    "encryption_public_key": "DEVICE_PUBLIC_KEY"
  }'

# Response: { "id": "pdev_...", "active": true, "encryption_key_id": "cHRL-UfvREIeEx3Q", ... }

Enregistrer un jeton qui existe déjà sous un autre user_id le déplace vers le nouvel utilisateur. Après une déconnexion et une connexion sur un téléphone partagé, les notifications de l'ancien utilisateur ne l'atteignent plus.

Chaque utilisateur garde au plus 20 appareils actifs. Un nouvel appareil au-delà retire l'appareil vu le moins récemment et déclenche push_device.deactivated avec la raison DEVICE_LIMIT. Chaque application garde au plus 1 000 000 d'appareils actifs en production et 1 000 en mode test : un nouvel appareil au-delà est refusé avec un 409 PUSH_DEVICE_LIMIT.

Quand un appareil est retiré

Apple et Google informent honkio quand un jeton n'est plus valide, par exemple après une désinstallation. honkio désactive l'appareil et déclenche push_device.deactivated avec la raison UNREGISTERED ou INVALID_TOKEN. Un jeton émis pour une autre application (DeviceTokenNotForTopic chez Apple, un jeton pour un autre identifiant de bundle, ou SENDER_ID_MISMATCH chez Google, un jeton d'un autre projet Firebase) est jugé selon que les informations d'identification ont déjà fonctionné : dès qu'une notification réelle a été acceptée avec elles, l'appareil est l'exception, il est donc désactivé avec la raison APP_MISMATCH et les informations d'identification restent inchangées. Avant cela, la configuration de l'application est la cause probable (un mauvais identifiant de bundle ou projet Firebase) : les informations d'identification sont marquées invalides, push_app.credentials_invalid est déclenché et l'appareil est conservé. Dans les deux cas, l'envoi échoue avec APP_MISMATCH. Une clé qu'Apple n'autorise pas pour votre identifiant de bundle (TopicDisallowed) est toujours un problème d'informations d'identification.

Appelez DELETE /v1/push/devices/:id à la déconnexion. Enregistrer de nouveau le jeton le réactive. Les appareils désactivés sont supprimés après 30 jours.

GET /v1/push/devices liste les appareils, avec les filtres app_id, user_id et active. Une clé de test ne voit que les appareils de test et une clé de production que ceux de production.