Erstellen von benutzerdefinierten Kanälen in Amazon Pinpoint

Amazon Pinpoint bietet integrierte Unterstützung für das Senden von Nachrichten über die Kanäle Push-Benachrichtigung, E-Mail, SMS und Sprache. Sie können Amazon Pinpoint auch so konfigurieren, dass Nachrichten über andere Kanäle gesendet werden, indem Sie benutzerdefinierte Kanäle erstellen. Benutzerdefinierte Kanäle in Amazon Pinpoint ermöglichen es Ihnen, Nachrichten über jeden Dienst zu senden, der über eine API verfügt, dazu gehören auch Dienste von Drittanbietern. Sie können mit APIs interagieren, indem Sie einen Webhook verwenden oder eine AWS Lambda Funktion aufrufen.

Die Segmente, an die Sie Kampagnen über benutzerdefinierte Kanäle senden, können Endpunkte aller Typen enthalten (d. h. Endpunkte, bei denen der Wert des ChannelType-Attributs EMAIL (E-MAIL), VOICE (SPRACHE), SMS, CUSTOM (BENUTZERDEFINIERT) oder einer der verschiedenen Endpunkttypen für Push-Benachrichtigung ist).

Erstellen einer Kampagne, die Nachrichten über einen benutzerdefinierten Kanal sendet

Um einer einzelnen Kampagne eine Lambda-Funktion oder einen Webhook zuzuweisen, verwenden Sie die Amazon-Pinpoint-API, um ein Kampagnenobjekt zu erstellen oder zu aktualisieren.

Das MessageConfiguration-Objekt in der Kampagne muss ebenfalls ein CustomMessage-Objekt enthalten. Dieses Objekt verfügt über ein Mitglied, Data. Der Wert von Data ist eine JSON-Zeichenfolge, die die Nachrichtennutzlast enthält, die Sie an den benutzerdefinierten Kanal senden möchten.

Die Kampagne muss ein CustomDeliveryConfiguration-Objekt enthalten. Geben Sie innerhalb des CustomDeliveryConfiguration-Objekts Folgendes an:

• EndpointTypes: Ein Array, das alle Endpunkttypen enthält, an die die Kampagne über benutzerdefinierte Kanäle gesendet werden soll. Es kann einen oder alle der folgenden Kanaltypen enthalten:

  • ADM

  • APNS

  • APNS_SANDBOX

  • APNS_VOIP

  • APNS_VOIP_SANDBOX

  • BAIDU

  • CUSTOM

  • EMAIL

  • GCM

  • SMS

  • VOICE

• DeliveryUri: Das Ziel, an das die Endpunkte gesendet werden. Sie können von Folgendem nur eines angeben:

  • den Amazon-Ressourcenname (ARN) einer Lambda-Funktion, die Sie ausführen möchten, wenn die Kampagne ausgeführt wird.

  • die URL des Webhooks, an den Sie Endpunktdaten senden möchten, wenn die Kampagne ausgeführt wird.

Anmerkung

Das Campaign-Objekt kann auch ein Hook-Objekt enthalten. Dieses Objekt wird nur zum Erstellen von Segmenten verwendet, die beim Ausführen einer Kampagne durch eine Lambda-Funktion angepasst werden. Weitere Informationen finden Sie unter Anpassen von Segmenten mit AWS Lambda.

Grundlegendes zu den Ereignisdaten, die über Amazon Pinpoint an benutzerdefinierte Kanäle gesendet werden

Bevor Sie eine Lambda-Funktion erstellen, die Nachrichten über einen benutzerdefinierten Kanal sendet, sollten Sie sich mit den Daten, die Amazon Pinpoint ausgibt, vertraut machen. Wenn eine Amazon-Pinpoint-Kampagne Nachrichten über einen benutzerdefinierten Kanal sendet, sendet sie eine Nutzlast an die Lambda-Zielfunktion, die dem folgenden Beispiel ähnelt:

{
  "Message":{},
  "Data":"The payload that's provided in the CustomMessage object in MessageConfiguration",
  "ApplicationId":"3a9b1f4e6c764ba7b031e7183example",
  "CampaignId":"13978104ce5d6017c72552257example",
  "TreatmentId":"0",
  "ActivityId":"575cb1929d5ba43e87e2478eeexample",
  "ScheduledTime":"2020-04-08T19:00:16.843Z",
  "Endpoints":{
    "1dbcd396df28ac6cf8c1c2b7fexample":{
      "ChannelType":"EMAIL",
      "Address":"[e-mail]",
      "EndpointStatus":"ACTIVE",
      "OptOut":"NONE",
      "Location":{
        "City":"Seattle",
        "Country":"USA"
      },
      "Demographic":{
        "Make":"OnePlus",
        "Platform":"android"
      },
      "EffectiveDate":"2020-04-01T01:05:17.267Z",
      "Attributes":{
        "CohortId":[
          "42"
        ]
      },
      "CreationDate":"2020-04-01T01:05:17.267Z"
    }
  }
}

Die Ereignisdaten stellen die folgenden Attribute bereit:

• ApplicationId: Die ID des Amazon-Pinpoint-Projekts, zu dem die Kampagne gehört.

• CampaignId: Die ID der Amazon-Pinpoint-Kampagne, die die Lambda-Funktion aufgerufen hat.

• TreatmentId: Die ID der Kampagnenvariante. Wenn Sie eine Standard-Kampagne erstellt haben, ist dieser Wert immer 0. Wenn Sie eine A/B-Testkampagne erstellt haben, ist dieser Wert eine ganze Zahl zwischen 0 und 4.

• ActivityId: Die ID der Aktivität, die von der Kampagne ausgeführt wird.

• ScheduledTime: Der Zeitpunkt, zu dem Amazon Pinpoint die Kampagne ausgeführt hat, wird im ISO 8601-Format angezeigt.

• Endpoints: Eine Liste der Endpunkte, die das Ziel der Kampagne waren. Jede Nutzlast kann bis zu 50 Endpunkte enthalten. Wenn das Segment, an das die Kampagne gesendet wurde, mehr als 50 Endpunkte enthält, ruft Amazon Pinpoint die Funktion wiederholt auf, mit bis zu 50 Endpunkten gleichzeitig, bis alle Endpunkte verarbeitet wurden.

Sie können diese Beispieldaten beim Erstellen und Testen Ihrer benutzerdefinierten Lambda-Kanalfunktion verwenden.

Konfigurieren von Webhooks

Wenn Sie einen Webhook verwenden, um Nachrichten über benutzerdefinierte Kanäle zu senden, muss die URL des Webhooks mit „https://“ beginnen. Die Webhook-URL darf nur alphanumerische Zeichen sowie die folgenden Symbole enthalten: Bindestrich (-), Punkt (.), Unterstrich (_), Tilde (~), Fragezeichen (?), Schrägstrich (/), Rautezeichen (#) und Semikolon (;). Die URL muss RFC3986 entsprechen.

Wenn Sie eine Kampagne erstellen, die eine Webhook-URL angibt, gibt Amazon Pinpoint einen HTTP HEAD an diese URL aus. Die Antwort auf die HEAD-Anforderung muss einen Header namens X-Amz-Pinpoint-AccountId enthalten. Der Wert dieses Headers muss Ihrer AWS Konto-ID entsprechen.

Konfigurieren von Lambda-Funktionen

Dieser Abschnitt bietet einen Überblick über die Schritte, die Sie ausführen müssen, wenn Sie eine Lambda-Funktion erstellen, die Nachrichten über einen benutzerdefinierten Kanal sendet. Zuerst erstellen Sie die Funktion. Danach fügen Sie der Funktion eine Ausführungsrichtlinie hinzu. Diese Richtlinie ermöglicht es Amazon Pinpoint, die Richtlinie auszuführen, wenn eine Kampagne ausgeführt wird.

Eine Einführung in die Erstellung von Lambda-Funktionen finden Sie unter Erstellen von Lambda-Funktionen im AWS Lambda Entwicklerhandbuch.

Beispiel-Lambda-Funktion

Das folgende Codebeispiel verarbeitet die Nutzlast und protokolliert die Anzahl der Endpunkte jedes Endpunkttyps. CloudWatch

import boto3
import random
import pprint
import json
import time

cloudwatch = boto3.client('cloudwatch')
    
def lambda_handler(event, context):
    customEndpoints = 0
    smsEndpoints = 0
    pushEndpoints = 0
    emailEndpoints = 0
    voiceEndpoints = 0
    numEndpoints = len(event['Endpoints'])
    
    print("Payload:\n", event)
    print("Endpoints in payload: " + str(numEndpoints))

    for key in event['Endpoints'].keys():
        if event['Endpoints'][key]['ChannelType'] == "CUSTOM":
            customEndpoints += 1
        elif event['Endpoints'][key]['ChannelType'] == "SMS":
            smsEndpoints += 1
        elif event['Endpoints'][key]['ChannelType'] == "EMAIL":
            emailEndpoints += 1
        elif event['Endpoints'][key]['ChannelType'] == "VOICE":
            voiceEndpoints += 1
        else:
            pushEndpoints += 1
            
    response = cloudwatch.put_metric_data(
        MetricData = [
            {
                'MetricName': 'EndpointCount',
                'Dimensions': [
                    {
                        'Name': 'CampaignId',
                        'Value': event['CampaignId']
                    },
                    {
                        'Name': 'ApplicationId',
                        'Value': event['ApplicationId']
                    }
                ],
                'Unit': 'None',
                'Value': len(event['Endpoints'])
            },
            {
                'MetricName': 'CustomCount',
                'Dimensions': [
                    {
                        'Name': 'CampaignId',
                        'Value': event['CampaignId']
                    },
                    {
                        'Name': 'ApplicationId',
                        'Value': event['ApplicationId']
                    }
                ],
                'Unit': 'None',
                'Value': customEndpoints
            },
            {
                'MetricName': 'SMSCount',
                'Dimensions': [
                    {
                        'Name': 'CampaignId',
                        'Value': event['CampaignId']
                    },
                    {
                        'Name': 'ApplicationId',
                        'Value': event['ApplicationId']
                    }
                ],
                'Unit': 'None',
                'Value': smsEndpoints
            },
            {
                'MetricName': 'EmailCount',
                'Dimensions': [
                    {
                        'Name': 'CampaignId',
                        'Value': event['CampaignId']
                    },
                    {
                        'Name': 'ApplicationId',
                        'Value': event['ApplicationId']
                    }
                ],
                'Unit': 'None',
                'Value': emailEndpoints
            },
            {
                'MetricName': 'VoiceCount',
                'Dimensions': [
                    {
                        'Name': 'CampaignId',
                        'Value': event['CampaignId']
                    },
                    {
                        'Name': 'ApplicationId',
                        'Value': event['ApplicationId']
                    }
                ],
                'Unit': 'None',
                'Value': voiceEndpoints
            },
            {
                'MetricName': 'PushCount',
                'Dimensions': [
                    {
                        'Name': 'CampaignId',
                        'Value': event['CampaignId']
                    },
                    {
                        'Name': 'ApplicationId',
                        'Value': event['ApplicationId']
                    }
                ],
                'Unit': 'None',
                'Value': pushEndpoints
            },
            {
                'MetricName': 'EndpointCount',
                'Dimensions': [
                ],
                'Unit': 'None',
                'Value': len(event['Endpoints'])
            },
            {
                'MetricName': 'CustomCount',
                'Dimensions': [
                ],
                'Unit': 'None',
                'Value': customEndpoints
            },
            {
                'MetricName': 'SMSCount',
                'Dimensions': [
                ],
                'Unit': 'None',
                'Value': smsEndpoints
            },
            {
                'MetricName': 'EmailCount',
                'Dimensions': [
                ],
                'Unit': 'None',
                'Value': emailEndpoints
            },
            {
                'MetricName': 'VoiceCount',
                'Dimensions': [
                ],
                'Unit': 'None',
                'Value': voiceEndpoints
            },
            {
                'MetricName': 'PushCount',
                'Dimensions': [
                ],
                'Unit': 'None',
                'Value': pushEndpoints
            }
        ],
        Namespace = 'PinpointCustomChannelExecution'
    )
    print("cloudwatchResponse:\n",response)

Wenn eine Amazon-Pinpoint-Kampagne diese Lambda-Funktion ausführt, sendet Amazon Pinpoint der Funktion eine Liste der Segmentmitglieder. Die Funktion zählt die Anzahl der Endpunkte jedes ChannelType. Diese Daten werden dann an Amazon gesendet CloudWatch. Sie können diese Metriken im Bereich Metriken der CloudWatch Konsole einsehen. Die Metriken sind im PinpointCustomChannelExecutionNamespace verfügbar.

Sie können dieses Codebeispiel so ändern, dass es auch eine Verbindung mit der API eines externen Dienstes herstellt, um Nachrichten über diesen Dienst zu senden.

Antwortformat der Lambda-Funktion für Amazon Pinpoint

Wenn Sie die Journey Mehrfach- oder Ja/Nein-Split verwenden möchten, um den Endpunktpfad nach einer benutzerdefinierten Kanalaktivität zu bestimmen, müssen Sie Ihre Lambda-Funktionsantwort in einem Format strukturieren, das Amazon Pinpoint verstehen kann, und dann Endpunkte auf den richtigen Pfad senden.

Der Antwortstruktur sollte das folgende Format aufweisen:

{ 
    <Endpoint ID 1>:{
        EventAttributes: {
            <Key1>: <Value1>,
            <Key2>: <Value2>, 
            ...
        } 
    }, 
    <Endpoint ID 2>:{ 
        EventAttributes: {
            <Key1>: <Value1>,
            <Key2>: <Value2>, 
            ...
        } 
    }, 
... 
}

Auf diese Weise können Sie dann einen Schlüssel und einen Wert auswählen, mit dem Sie den Pfad der Endpunkte bestimmen möchten.

Gewähren der Berechtigung zum Aufrufen der Lambda-Funktion an Amazon Pinpoint

Sie können die AWS Command Line Interface (AWS CLI) verwenden, um der Lambda-Funktionsrichtlinie, die Ihrer Lambda-Funktion zugewiesen ist, Berechtigungen hinzuzufügen. Um Amazon Pinpoint den Aufruf einer Funktion zu ermöglichen, verwenden Sie den Befehl add-permission, wie im folgenden Beispiel gezeigt:

aws lambda add-permission \
--function-name myFunction \ 
--statement-id sid0 \
--action lambda:InvokeFunction \
--principal pinpoint.us-east-1.amazonaws.com \
--source-arn arn:aws:mobiletargeting:us-east-1:111122223333:apps/*
--source-account 111122223333

Gehen Sie im vorhergehenden Befehl wie folgt vor:

• Ersetzen Sie myFunction durch den Namen der Lambda-Funktion.

• Ersetzen Sie us-east-1 durch die AWS Region, in der Sie Amazon Pinpoint verwenden.

• Ersetzen Sie 111122223333 durch Ihre AWS -Konto-ID.

Wenn Sie den Befehl add-permission ausführen, gibt Lambda die folgende Ausgabe zurück:

{
  "Statement": "{\"Sid\":\"sid\",
    \"Effect\":\"Allow\",
    \"Principal\":{\"Service\":\"pinpoint.us-east-1.amazonaws.com\"},
    \"Action\":\"lambda:InvokeFunction\",
    \"Resource\":\"arn:aws:lambda:us-east-1:111122223333:function:myFunction\",
    \"Condition\":
      {\"ArnLike\":
        {\"AWS:SourceArn\":
         \"arn:aws:mobiletargeting:us-east-1:111122223333:apps/*\"}},
      {\"StringEquals\": 
        {\"AWS:SourceAccount\": 
          \"111122223333\"}}}
}

Der Statement-Wert ist eine JSON-Zeichenfolgenversion der Anweisung, die der Lambda-Funktionsrichtlinie hinzugefügt wurde.

Weiteres Einschränken der Ausführungsrichtlinie

Sie können die Ausführungsrichtlinie ändern, indem Sie sie auf ein bestimmtes Amazon-Pinpoint-Projekt beschränken. Ersetzen Sie dazu das * im vorangegangenen Beispiel durch die eindeutige ID des Projekts. Sie können die Richtlinie weiter einschränken, indem Sie sie auf eine bestimmte Kampagne beschränken. Um beispielsweise die Richtlinie so einzuschränken, dass nur eine Kampagne mit der Kampagnen-ID 95fee4cd1d7f5cd67987c1436example in einem Projekt mit der Projekt-ID dbaf6ec2226f0a9a8615e3ea5example zugelassen wird, verwenden Sie den folgenden Wert für das source-arn-Attribut:

arn:aws:mobiletargeting:us-east-1:111122223333:apps/dbaf6ec2226f0a9a8615e3ea5example/campaigns/95fee4cd1d7f5cd67987c1436example

Anmerkung

Wenn Sie die Ausführung der Lambda-Funktion auf eine bestimmte Kampagne beschränken, müssen Sie die Funktion zunächst mit einer weniger restriktiven Richtlinie erstellen. Als Nächstes müssen Sie die Kampagne in Amazon Pinpoint erstellen und die Funktion auswählen. Abschließend müssen Sie die Ausführungsrichtlinie aktualisieren, damit diese auf die angegebene Kampagne referenziert wird.