Creación de canales personalizados en Amazon Pinpoint - Amazon Pinpoint
Creación de una campaña que envía mensajes a través de un canal personalizadoDescripción de los datos de eventosConfiguración de webhooksConfiguración de las funciones de Lambda

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Creación de canales personalizados en Amazon Pinpoint

Amazon Pinpoint incluye soporte integrado para enviar mensajes a través de la notificación de inserción, correo electrónico, SMS y canales de voz. También puede configurar Amazon Pinpoint para enviar mensajes a través de otros canales creando canales personalizados. Los canales personalizados de Amazon Pinpoint le permiten enviar mensajes a través de cualquier servicio que tenga una API, incluidos servicios de terceros. Puede interactuar con las API mediante un webhook o llamando a una función de AWS Lambda.

Los segmentos a los que envía campañas de canal personalizadas pueden contener puntos de enlace de todos los tipos (es decir, puntos de enlace donde el valor del atributo ChannelType es EMAIL, VOICE, SMS, CUSTOM o uno de los distintos tipos de puntos de enlace de notificación push).

Creación de una campaña que envía mensajes a través de un canal personalizado

Para asignar una función de Lambda o webhook a una campaña individual, use la API de Amazon Pinpoint a fin de crear o actualizar un objeto de campaña.

El objeto MessageConfiguration de la campaña también debe contener un objeto CustomMessage. Este objeto tiene un miembro, Data. El valor de Data es una cadena JSON que contiene la carga útil del mensaje que desea enviar al canal personalizado.

La campaña tiene que contener un objeto CustomDeliveryConfiguration. En el objeto CustomDeliveryConfiguration, especifique lo siguiente:

  • EndpointTypes: una matriz que contiene todos los tipos de puntos de conexión a los que se debe enviar la campaña de canales personalizados. Puede contener alguno o todos los tipos de canales siguientes:

    • ADM

    • APNS

    • APNS_SANDBOX

    • APNS_VOIP

    • APNS_VOIP_SANDBOX

    • BAIDU

    • CUSTOM

    • EMAIL

    • GCM

    • SMS

    • VOICE

  • DeliveryUri: el destino al que se envían los puntos de conexión. Puede especificar solo una de las siguientes opciones:

    • El nombre de recurso de Amazon (ARN) de una función de Lambda que desea ejecutar cuando se ejecute la campaña.

    • La dirección URL del webhook al que desea enviar datos de punto de enlace cuando se ejecute la campaña.

nota

El objeto Campaign también puede contener un objeto Hook. Este objeto solo se utiliza para crear segmentos personalizados por una función de Lambda cuando se ejecuta una campaña. Para obtener más información, consulte Personalización de segmentos con AWS Lambda.

Descripción de los datos de eventos que Amazon Pinpoint envía a canales personalizados

Antes de crear una función de Lambda que envíe mensajes a través de un canal personalizado, debe familiarizarse con los datos que emite Amazon Pinpoint. Cuando una campaña de Amazon Pinpoint envía mensajes a través de un canal personalizado, envía una carga a la función de Lambda de destino similar al siguiente ejemplo:

{
  "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":"mary.major@example.com",
      "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"
    }
  }
}

Los datos de eventos proporciona los siguientes atributos:

  • ApplicationId: el ID del proyecto de Amazon Pinpoint al que pertenece la campaña.

  • CampaignId: el ID de la campaña de Amazon Pinpoint que invocó la función de Lambda.

  • TreatmentId: el ID de la variante de la campaña. Si ha creado una campaña estándar, este valor siempre es 0. Si ha creado una campaña de prueba A/B, este valor es un entero entre 0 y 4.

  • ActivityId: el ID de la actividad que está realizando la campaña.

  • ScheduledTime: la hora en que Amazon Pinpoint ejecutó la campaña, que se muestra en formato ISO 8601.

  • Endpoints: una lista de los puntos de conexión a los que se dirigió la campaña. Cada carga útil puede contener hasta 50 puntos de enlace. Si el segmento al que se envió la campaña contiene más de 50 puntos de conexión, Amazon Pinpoint invoca la función reiteradamente, de 50 en 50 puntos de conexión, hasta que se hayan procesado todos ellos.

Puede utilizar estos datos de ejemplo al crear y probar la función de Lambda de canal personalizado.

Configuración de webhooks

Si utiliza un webhook para enviar mensajes de canal personalizado, la URL del webhook debe comenzar por «https://». La URL del webhook solo puede contener caracteres alfanuméricos, más los siguientes símbolos: guion (-), punto (.), guion bajo (_), virgulilla (~), signo de interrogación (?), barra inclinada (/), signo de almohadilla (#) y punto y coma (:). La URL debe cumplir con RFC3986.

Cuando crea una campaña que especifica una dirección URL de webhook, Amazon Pinpoint emite un HTTP HEAD a esa URL. La respuesta a la solicitud HEAD debe contener un encabezado llamado X-Amz-Pinpoint-AccountId. El valor de este encabezado debe ser igual a su ID de cuenta de AWS.

Configuración de las funciones de Lambda

En esta sección se proporciona información general de los pasos que debe seguir al crear una función de Lambda que envía mensajes a través de un canal personalizado. Primero, cree la función. A continuación, agregue una política de ejecución a la función. Esta política permite a Amazon Pinpoint ejecutarla cuando se ejecuta una campaña.

Para obtener una introducción a la creación de funciones de Lambda, consulte Creación de funciones de Lambda en la Guía para desarrolladores de AWS Lambda.

Ejemplo de función de Lambda

En el ejemplo de código siguiente se procesa la carga y se registra el número de puntos de conexión de cada tipo de punto de conexión en 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)

Cuando una campaña de Amazon Pinpoint ejecuta esta función de Lambda, Amazon Pinpoint envía a la función una lista de miembros del segmento. La función cuenta el número de puntos de enlace de cada ChannelType. A continuación, envía esos datos a Amazon CloudWatch. Puede consultar estas métricas en la sección Métricas de la consola de CloudWatch. Las métricas están disponibles en el espacio de nombres PinpointCustomChannelExecution.

Puede modificar este ejemplo de código para que también se conecte a la API de un servicio externo para enviar mensajes a través de ese servicio.

Formato de respuesta de función de Lambda para Amazon Pinpoint

Si desea utilizar el recorrido multivariante o la división sí/no para determinar la ruta del punto de conexión después de una actividad de canal personalizada, debe estructurar la respuesta de la función de Lambda en un formato que Amazon Pinpoint pueda entender y, a continuación, enviar los puntos de conexión por la ruta correcta.

La estructura de la respuesta debe estar en el siguiente formato:

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

Esto le permitirá seleccionar una clave y el valor que desee para determinar la ruta de los puntos de conexión.

Conceder a Amazon Pinpoint permiso para invocar la función de Lambda

Puede utilizar la AWS Command Line Interface (AWS CLI) para agregar permisos a la política de función de Lambda asignada a la función de Lambda. Para permitir a Amazon Pinpoint invocar una función, utilice el comando add-permission de Lambda, como se muestra en el ejemplo siguiente:

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

En el comando anterior, haga lo siguiente.

  • Sustituya myFunction por el nombre de la función de Lambda.

  • Sustituya us-east-1 por la región de AWS donde utiliza Amazon Pinpoint.

  • Reemplace 111122223333 por su ID de cuenta de AWS.

Cuando ejecuta el comando add-permission, Lambda devuelve la siguiente salida:

{
  "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\"}}}
}

El valor de Statement es una versión de cadena JSON de la instrucción que se agrega a la política de la función de Lambda.

Restricción adicional de la política de ejecución

Puede modificar la política de ejecución restringiéndola a un proyecto de Amazon Pinpoint específico. Para ello, sustituya * en el ejemplo anterior por el ID único del proyecto. Puede restringir aún más la política limitándola a una campaña específica. Por ejemplo, para restringir la política de modo que solo permita una campaña con el ID de campaña 95fee4cd1d7f5cd67987c1436example en un proyecto con el ID de proyecto dbaf6ec2226f0a9a8615e3ea5example, utilice el valor siguiente para el atributo source-arn:

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

Si restringe la ejecución de la función de Lambda a una campaña específica, primero tiene que crear la función con una política menos restrictiva. A continuación, debe crear la campaña en Amazon Pinpoint y elegir la función. Por último, debe actualizar la política de ejecución para hacer referencia a la campaña especificada.