Erstellen eines Plattformendpunkts - Amazon Simple Notification Service

Erstellen eines Plattformendpunkts

Wenn eine App oder ein Mobilgerät bei einem Push-Benachrichtigungsservice registriert werden, gibt der Push-Benachrichtigungsservice ein Geräte-Token zurück. Amazon SNS verwendet das Gerätetoken, um einen mobilen Endpunkt zu erstellen, zu dem mobile Push-Benachrichtigungen direkt gesendet werden können. Weitere Informationen erhalten Sie unter Voraussetzungen für Amazon SNS-Benutzerbenachrichtigungen und Übersicht über den Benutzerbenachrichtigungsprozess.

In diesem Abschnitt wird der empfohlene Ansatz zum Erstellen eines Plattformendpunkts.

Erstellen eines Plattformendpunkts

Um Push-Benachrichtigungen zu einer App per Amazon SNS zu senden, muss zuerst das Geräte-Token der App bei Amazon SNS registriert werden, indem die "create platform endpoint"-Aktion aufgerufen wird. Diese Aktion verwendet den Amazon Resource Name (ARN) der Plattformanwendung und das Geräte-Token als Parameter und gibt den ARN des erstellten Plattformendpunkts zurück.

Die „create platform endpoint“-Aktion führt Folgendes aus:

  • Wenn der Plattformendpunkt bereits vorhanden ist, wird er nicht neu erstellt. Dem Aufrufer wird der ARN des vorhandenen Plattformendpunkts zurückgegeben.

  • Wenn der Plattformendpunkt mit demselben Geräte-Token, aber anderen Einstellungen vorhanden ist, wird er nicht erneut erstellt. Es wird eine Ausnahme für den Aufrufer ausgelöst.

  • Wenn der Plattformendpunkt nicht vorhanden ist, wird er erstellt. Dem Aufrufer wird der ARN des neu erstellten Plattformendpunkts zurückgegeben.

Sie sollten die Aktion nicht direkt bei jedem Start der Anwendung aufrufen. Sie sorgt nicht immer für die Bereitstellung eines funktionierenden Endpunkts. Dies kann zum Beispiel der Fall sein, wenn eine App auf einem Gerät deinstalliert und neu installiert wird und der Endpunkt für diese bereits vorhanden aber deaktiviert ist. Ein erfolgreicher Registrierungsprozess sollte folgendermaßen aussehen:

  1. Stellen Sie sicher, dass ein Plattformendpunkt für diese App-Geräte-Kombination vorhanden ist.

  2. Stellen Sie sicher, dass das Geräte-Token im Plattformendpunkt das neueste gültige Geräte-Token ist.

  3. Stellen Sie sicher, dass der Plattformendpunkt aktiviert und bereit ist.

Pseudo-Code

Der folgende Pseudo-Code beschreibt ein empfohlenes Verfahren für die Erstellung eines funktionierenden, aktuellen, aktivierten Plattformendpunkts in einer Vielzahl von Startbedingungen. Dieser Ansatz funktioniert, wenn die App zum ersten Mal oder erneut registriert wird. Es ist egal, ob der Plattformendpunkt für diese App bereits vorhanden ist, ob der Plattformendpunkt aktiviert ist, ob er das richtige Geräte-Token hat und so weiter. Der Code kann mehrfach hintereinander aufgerufen werden. Er wird keine doppelten Plattformendpunkte erstellen oder einen vorhandenen Plattformendpunkt ändern, der bereits auf dem neuesten Stand und aktiviert ist.

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

Dieser Ansatz kann jederzeit verwendet werden, wenn die App sich registrieren oder erneut registrieren möchte. Er kann auch beim Benachrichtigen von Amazon SNS über eine Änderung des Geräte-Tokens verwendet werden. In diesem Fall können Sie einfach eine Aktion mit dem neuesten Geräte-Token-Wert aufrufen. Es gibt einige wichtige Punkte zu diesem Ansatz:

  • Es gibt zwei Fälle, in denen die „create platform endpoint“-Aktion aufgerufen werden kann. Sie kann direkt zu Beginn aufgerufen werden, wenn die App ihren eigenen Plattformendpunkt-ARN nicht kennt (z. B. während der Erstregistrierung). Sie kann auch aufgerufen werden, wenn der erste „get endpoint attributes“-Aktionsaufruf mit einer „Not-Found“-Ausnahme fehlschlägt (z. B. wenn die Anwendung ihren ARN kennt, dieser aber gelöscht wurde).

  • Die „get endpoint attributes“-Aktion wird aufgerufen, um den Status des Plattformendpunkts zu überprüfen, obwohl der Plattformendpunkt gerade erstellt wurde. Dies geschieht, wenn der Plattformendpunkt bereits vorhanden, aber deaktiviert ist. In diesem Fall ist die „create platform endpoint“-Aktion erfolgreich, aber der Plattformendpunkt wird nicht aktiviert. Daher müssen Sie den Status des Plattformendpunkts vor der Rückgabe eines Erfolgs prüfen.

AWS-SDK-Beispiel

Der folgende Code zeigt, wie Sie den vorherigen Pseudo-Code mithilfe der Amazon SNS-Clients implementieren können, die von den AWS-SDKs bereitgestellt werden.

Um ein AWS-SDK zu verwenden, müssen Sie es mit Ihren Anmeldeinformationen konfigurieren. Weitere Informationen finden Sie unter Freigegebene Konfigurations- und Anmeldeinformationsdateien im AWS-Referenzhandbuch zu SDKs und Tools.

Java
SDK für Java 1.x

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; } }
  • Weitere Anleitungen und mehr Code finden Sie im GitHub.

Weitere Informationen finden Sie unter Mobile Push-API-Aktionen.

Troubleshooting

Wiederholtes Aufrufen von „Create Platform Endpoint“ mit einem veralteten Geräte-Token

Speziell für FCM-Endpunkte gehen Sie möglicherweise davon aus, dass es sich empfiehlt, das erste Geräte-Token der Anwendung zu speichern und dann „create platform endpoint“ bei jedem Anwendungsstart mit diesem Geräte-Token aufzurufen. Dies scheint sinnvoll, da die App sich nicht mehr um den Status des Geräte-Tokens kümmern muss und Amazon SNS das Geräte-Token automatisch auf den aktuellen Wert aktualisiert. Diese Lösung hat jedoch mehrere ernsthafte Probleme:

  • Amazon SNS stützt sich auf das Feedback von FCM, um abgelaufene Geräte-Tokens durch neue Geräte-Tokens zu aktualisieren. FCM erhält einige Zeit Informationen zu alten Geräte-Tokens. Dies gilt jedoch nicht unbegrenzt. Sobald FCM die Verbindung zwischen dem alten Geräte-Token und dem neuen Geräte-Token vergessen hat, ist Amazon SNS nicht mehr in der Lage, das im Plattformendpunkt gespeicherte Geräte-Token auf den korrekten Wert zu aktualisieren. Stattdessen wird der Plattformendpunkt einfach deaktiviert.

  • Die Plattformanwendung enthält mehrere Plattformendpunkte mit demselben Geräte-Token.

  • Amazon SNS arbeitet mit einem Kontingent an Plattformendpunkten, die gleichzeitig mit demselben Geräte-Token gestartet werden können. Irgendwann wird die Erstellung neuer Endpunkte mit einer „Invalid Parameter“-Ausnahme und der Fehlermeldung „This endpoint is already registered with a different token.“ fehlschlagen.

Erneutes Aktivieren eines Plattformendpunktes mit einem ungültigen Geräte-Token

Wenn eine mobile Plattform (z. B. APNs oder FCM) Amazon SNS darüber informiert, dass das in der Veröffentlichungsanforderung verwendete Geräte-Token ungültig ist, deaktiviert Amazon SNS den Plattformendpunkt für dieses Geräte-Token. Amazon SNS weist dann nachfolgende Veröffentlichungen für das Geräte-Token zurück. Möglicherweise glauben Sie, Sie könnten einfach den Plattformendpunkt neu aktivieren und so weiter veröffentlichen, doch wird dies in den meisten Fällen nicht funktionieren. Die veröffentlichten Nachrichten werden nicht zugestellt und der Plattformendpunkt wird bald wieder deaktiviert.

Der Grund hierfür ist, dass das Geräte-Token des Plattformendpunkts wirklich ungültig ist. Zustellungen können nicht abgeschlossen werden, da es nicht mehr mit einer installierten App übereinstimmt. Bei der nächsten Veröffentlichung informiert die mobile Plattform Amazon SNS erneut darüber, dass das Geräte-Token ungültig ist. Amazon SNS wird den Plattformendpunkt wieder deaktivieren.

Um einen deaktivierten Plattformendpunkt zu reaktivieren, muss dieser einem gültigen Geräte-Token zugeordnet (über einen „set endpoint attributes“-Aktionsaufruf) sein und dann aktiviert werden. Nur dann werden Zustellungen an den Plattformendpunkt erfolgreich sein. Das erneute Aktivieren eines Plattformendpunkts ohne Aktualisierung des Geräte-Tokens funktioniert nur, wenn ein dem Endpunkt zugeordnetes Geräte-Token ungültig ist und wieder gültig wird. Dies kann zum Beispiel der Fall sein, wenn eine App deinstalliert und dann auf demselben Mobilgerät neu installiert wurde und dasselbe Geräte-Token erhält. Der oben gezeigte Ansatz geht so vor. Er stellt sicher, dass der Plattformendpunkt erst dann neu aktiviert wird, wenn überprüft wurde, dass das ihm zugeordnete Geräte-Token im Moment verfügbar ist.