Création d'un point de terminaison de plateforme - Amazon Simple Notification Service

Création d'un point de terminaison de plateforme

Lorsqu'une application et un appareil mobile s'inscrivent auprès d'un service de notification push, le service de notification push renvoie un jeton d'appareil. Amazon SNS utilise ce jeton d'appareil pour créer un point de terminaison mobile, auquel il peut envoyer directement des messages de notification push. Pour plus d'informations, veuillez consulter Conditions préalables pour les notifications utilisateur Amazon SNS et Présentation du processus de notification utilisateur.

Cette section décrit l'approche recommandée pour la création d'un point de terminaison de plateforme.

Création d'un point de terminaison de plateforme

Pour envoyer des notifications à une application à l'aide d'Amazon SNS, le jeton d'appareil de cette application doit d'abord être inscrit auprès d'Amazon SNS grâce à l'appel de l'action de création d'un point de terminaison de plateforme. Cette action utilise l'Amazon Resource Name (ARN) de l'application de plateforme et le jeton d'appareil en tant que paramètres et renvoie l’ARN du point de terminaison de plateforme créé.

L'action de création de point de terminaison de plateforme effectue les opérations suivantes :

  • Si le point de terminaison de plateforme existe déjà, ne le recréez pas. Renvoyez à l'appelant l'ARN du point de terminaison de plateforme existant.

  • Si le point de terminaison de plateforme existe déjà avec le même jeton d'appareil, mais des paramètres différents, ne le recréez pas. Envoyez une exception à l'appelant.

  • Si le point de terminaison de plateforme n'existe pas, créez-le. Renvoyez à l'appelant l'ARN du point de terminaison de plateforme nouvellement créé.

Vous ne devez pas appeler l'action de création de point de terminaison de plateforme à chaque démarrage d'une application, car cette approche ne fournit pas toujours un point de terminaison en état de fonctionnement. Cela peut se produire, par exemple, lorsqu'une application est désinstallée et réinstallée sur le même appareil et que son point de terminaison existe déjà mais est désactivé. Un processus d'inscription réussi doit effectuer les opérations suivantes :

  1. S'assurer qu'un point de terminaison de plateforme existe pour cette combinaison application-appareil.

  2. Vérifier que le jeton d'appareil dans le point de terminaison de plateforme est le jeton d'appareil valide le plus récent.

  3. S'assurer que le point de terminaison de plateforme est activé et prêt à être utilisé.

Code fictif

Le pseudo-code suivant décrit une pratique recommandée pour la création d'un point de terminaison de plateforme en état de fonctionnement, actuel et activé dans une large gamme de conditions de démarrage. Cette approche fonctionne s’il s'agit de l’enregistrement initial de l'application, si le point de terminaison de plateforme pour cette application existe déjà et si le point de terminaison de plateforme est activé, possède le jeton d'appareil correct, etc. Il n'est pas risqué de l'appeler plusieurs fois d'affilée, car il ne créera pas de points de terminaison de plateforme en double ou ne modifiera pas un point de terminaison de plateforme existant s'il est déjà à jour et activé.

retrieve the latest device token from the mobile operating system if (the platform endpoint ARN is not stored) # this is a first-time registration call create platform endpoint store the returned platform endpoint ARN endif call get endpoint attributes on the platform endpoint ARN if (while getting the attributes a not-found exception is thrown) # the platform endpoint was deleted call create platform endpoint with the latest device token store the returned platform endpoint ARN else if (the device token in the endpoint does not match the latest one) or (get endpoint attributes shows the endpoint as disabled) call set endpoint attributes to set the latest device token and then enable the platform endpoint endif endif

Cette approche peut servir chaque fois que l'application veut s'enregistrer ou se ré-enregistrer. Elle peut également être utilisée lors de la notification d'une modification du jeton d'appareil à Amazon SNS. Dans ce cas, il vous suffit d'appeler l'action avec la dernière valeur de jeton d'appareil. Voici quelques points à prendre en compte à propos de cette approche :

  • Il existe deux cas dans lesquels elle peut appeler l'action de création de point de terminaison de plateforme. Elle peut être appelée au tout début, lorsque l'application ne connaît pas son propre ARN de point de terminaison de plateforme, comme cela se produit lors d'une inscription initiale. Elle est également appelée si l'action initiale d'obtention des attributs de point de terminaison échoue avec une exception introuvable, comme cela se produit si l'application connaît son ARN de point de terminaison, mais qu'il a été supprimé.

  • L'action d'obtention d'attributs de point de terminaison est appelée pour vérifier l'état du point de terminaison de plateforme, même si ce dernier vient d'être créé. Cela se produit lorsque le point de terminaison de plateforme existe déjà mais est désactivé. Dans ce cas, l'action de création de point de terminaison de plateforme réussit, mais n'active pas le point de terminaison de plateforme. Vous devez donc vérifier l'état du point de terminaison de plateforme avant d'indiquer la réussite.

Exemples de kit SDK AWS

Les exemples suivants montrent comment implémenter le pseudo-code précédent à l'aide des clients Amazon SNS qui sont fournis par les kits SDK AWS.

Pour utiliser un kit SDK AWS, vous devez le configurer avec vos informations d'identification. Pour plus d'informations, consultez Les fichiers de configuration et d'informations d'identification partagés dans le AWS Guide de référence des kits SDK et des outils.

Java
Kit SDK pour Java 1.x
Astuce

Pour découvrir comment configurer et exécuter cet exemple, consultez GitHub.

class RegistrationExample { AmazonSNSClient client = new AmazonSNSClient(); //provide credentials here String arnStorage = null; public void registerWithSNS() { String endpointArn = retrieveEndpointArn(); String token = "Retrieved from the mobile operating system"; boolean updateNeeded = false; boolean createNeeded = (null == endpointArn); if (createNeeded) { // No platform endpoint ARN is stored; need to call createEndpoint. endpointArn = createEndpoint(); createNeeded = false; } System.out.println("Retrieving platform endpoint data..."); // Look up the platform endpoint and make sure the data in it is current, even if // it was just created. try { GetEndpointAttributesRequest geaReq = new GetEndpointAttributesRequest() .withEndpointArn(endpointArn); GetEndpointAttributesResult geaRes = client.getEndpointAttributes(geaReq); updateNeeded = !geaRes.getAttributes().get("Token").equals(token) || !geaRes.getAttributes().get("Enabled").equalsIgnoreCase("true"); } catch (NotFoundException nfe) { // We had a stored ARN, but the platform endpoint associated with it // disappeared. Recreate it. createNeeded = true; } if (createNeeded) { createEndpoint(token); } System.out.println("updateNeeded = " + updateNeeded); if (updateNeeded) { // The platform endpoint is out of sync with the current data; // update the token and enable it. System.out.println("Updating platform endpoint " + endpointArn); Map attribs = new HashMap(); attribs.put("Token", token); attribs.put("Enabled", "true"); SetEndpointAttributesRequest saeReq = new SetEndpointAttributesRequest() .withEndpointArn(endpointArn) .withAttributes(attribs); client.setEndpointAttributes(saeReq); } } /** * @return never null * */ private String createEndpoint(String token) { String endpointArn = null; try { System.out.println("Creating platform endpoint with token " + token); CreatePlatformEndpointRequest cpeReq = new CreatePlatformEndpointRequest() .withPlatformApplicationArn(applicationArn) .withToken(token); CreatePlatformEndpointResult cpeRes = client .createPlatformEndpoint(cpeReq); endpointArn = cpeRes.getEndpointArn(); } catch (InvalidParameterException ipe) { String message = ipe.getErrorMessage(); System.out.println("Exception message: " + message); Pattern p = Pattern .compile(".*Endpoint (arn:aws:sns[^ ]+) already exists " + "with the same [Tt]oken.*"); Matcher m = p.matcher(message); if (m.matches()) { // The platform endpoint already exists for this token, but with additional // custom data that createEndpoint doesn't want to overwrite. Use the // existing platform endpoint. endpointArn = m.group(1); } else { // Rethrow the exception, because the input is actually bad. throw ipe; } } storeEndpointArn(endpointArn); return endpointArn; } /** * @return the ARN the app was registered under previously, or null if no * platform endpoint ARN is stored. */ private String retrieveEndpointArn() { // Retrieve the platform endpoint ARN from permanent storage, // or return null if null is stored. return arnStorage; } /** * Stores the platform endpoint ARN in permanent storage for lookup next time. * */ private void storeEndpointArn(String endpointArn) { // Write the platform endpoint ARN to permanent storage. arnStorage = endpointArn; } }

Pour plus d'informations, consultez Actions d'API push mobile.

Dépannage

Appel répété de la création du point de terminaison de plateforme avec un jeton d'appareil obsolète

En particulier pour les points de terminaison FCM, vous pouvez penser qu'il est préférable de stocker le premier jeton d'appareil émis par l'application, puis d'appeler la création du point de terminaison de plateforme avec ce jeton d'appareil à chaque démarrage de l'application. Cela peut sembler correct dans la mesure où l'application n'a pas à gérer l'état du jeton d'appareil et où Amazon SNS met automatiquement à jour le jeton d'appareil à l'aide de sa valeur la plus récente. Cependant, cette solution présente un certain nombre de problèmes graves :

  • Amazon SNS s'appuie sur les retours de FCM pour remplacer les jetons d'appareil expirés par de nouveaux jetons d'appareil. FCM conserve les informations concernant les anciens jetons d'appareil un certain temps, mais pas indéfiniment. Une fois que FCM a oublié la connexion entre l'ancien jeton d'appareil et le nouveau, Amazon SNS ne peut plus mettre à jour le jeton d'appareil stocké dans le point de terminaison de plateforme avec la valeur correcte ; au lieu de cela, il désactive simplement le point de terminaison de plateforme.

  • L'application de plateforme contient plusieurs points de terminaison de plateforme correspondant au même jeton d'appareil.

  • Amazon SNS impose un quota au nombre de points de terminaison de plateforme qui peuvent être créés en commençant par le même jeton d'appareil. Enfin, la création de nouveaux points de terminaison échoue avec une exception de paramètre non valide et le message d'erreur suivant : « This endpoint is already registered with a different token (Ce point de terminaison est déjà enregistré avec un jeton différent) ».

Réactivation d'un point de terminaison de plateforme associé à un jeton d'appareil non valide

Lorsqu'une plateforme mobile (par exemple, APNs ou FCM) informe Amazon SNS que le jeton d'appareil utilisé dans la demande de publication n'était pas valide, Amazon SNS désactive le point de terminaison de plateforme associée à ce jeton d'appareil. Amazon SNS rejettera ensuite les publications ultérieures sur ce jeton d'appareil. Bien que vous puissiez penser qu'il est préférable de simplement réactiver le point de terminaison de plateforme et de continuer la publication, dans la plupart des cas, cela ne fonctionnera pas : les messages qui sont publiés ne sont pas diffusés et le point de terminaison de plateforme est à nouveau désactivé peu de temps après.

En effet, cela vient du fait que le jeton d'appareil associé au point de terminaison de plateforme est réellement non valide. Les diffusions à ce point de terminaison ne peuvent pas réussir, car il ne correspond plus à aucune application installée. Lors de la prochaine publication, la plateforme mobile informera à nouveau Amazon SNS que le jeton d'appareil n'est pas valide et Amazon SNS désactivera à nouveau le point de terminaison de plateforme.

Pour réactiver un point de terminaison de plateforme désactivé, ce dernier doit être associé à un jeton d'appareil valide (avec un appel d'action de définition d'attributs de point de terminaison), puis activé. Les diffusions à ce point de terminaison de plateforme ne réussiront qu'à ce moment-là. La seule fois où la réactivation d'un point de terminaison de plateforme fonctionne sans mise à jour de son jeton d'appareil est lorsqu'un jeton d'appareil associé à ce point de terminaison qui était non valide redevient valide. Cela peut se produire, par exemple, lorsqu'une application a été désinstallée, puis réinstallée sur le même appareil mobile et reçoit le même jeton d'appareil. L'approche présentée ci-dessus effectue cette opération, en s'assurant de ne réactiver un point de terminaison de plateforme qu'après avoir vérifié que le jeton d'appareil qui lui est associé est le dernier en date disponible.