Personalización de segmentos con AWS Lambda

Esta es una documentación preliminar para una característica en versión beta pública. Está sujeta a cambios.

Puede utilizarla AWS Lambda para personalizar la forma en que una campaña de Amazon Pinpoint atrae a su público objetivo. Con AWS Lambda, puede modificar el segmento de la campaña en el momento en que Amazon Pinpoint envía el mensaje de la campaña.

AWS Lambda es un servicio informático que puede utilizar para ejecutar código sin aprovisionar ni administrar servidores. Puede empaquetar el código y cargarlo en Lambda como funciones de Lambda. Lambda ejecuta una función cuando se invoca la función, lo que se podría hacer de forma manual o automática en respuesta a eventos. Para obtener más información, consulte la Guía para desarrolladores de AWS Lambda.

Para asignar una función de Lambda a una campaña, defina la configuración CampaignHook de la campaña mediante el recurso de campaña en la API de Amazon Pinpoint. Entre estos ajustes se incluye el nombre de la función de Lambda. También se incluye el modo CampaignHook, que establece si Amazon Pinpoint recibe un valor de retorno de la función.

Una función de Lambda que asigne a una campaña se conoce como una extensión de Amazon Pinpoint.

Con la configuración de CampaignHook definida, Amazon Pinpoint invoca automáticamente la función de Lambda cuando ejecuta la campaña, antes de enviar el mensaje de la campaña. Cuando Amazon Pinpoint invoca la función, proporciona datos de eventos sobre el envío de mensajes. Estos datos incluyen el segmento de la campaña, que es la lista de puntos de conexión a los que Amazon Pinpoint envía el mensaje.

Si el modo CampaignHook está establecido en FILTER, Amazon Pinpoint permite que la función modifique y devuelva el segmento antes de enviar el mensaje. Por ejemplo, la función podría actualizar las definiciones del punto de conexión con atributos que contienen datos de un origen externo a Amazon Pinpoint. O bien, la función podría filtrar el segmento quitando ciertos puntos de enlace dependiendo de las condiciones del código de la función. Una vez Amazon Pinpoint reciba el segmento modificado de la función, envía el mensaje a cada uno de los puntos de conexión del segmento utilizando el canal de entrega de la campaña.

Al procesar tus segmentos con ellos AWS Lambda, tienes más control sobre a quién envías los mensajes y qué contienen esos mensajes. Puede adaptar sus campañas en tiempo real, en el momento en que los mensajes de la campaña se envíen. Filtrar segmentos le permite atraer a subconjuntos de los segmentos definidos más concretamente. Agregar o actualizar los atributos de los puntos de enlace también permite que haya nuevos datos disponibles para las variables de mensajes.

nota

También puede utilizar la configuración de CampaignHook para asignar una función de Lambda que administre la entrega de mensajes. Este tipo de función resulta útil para la entrega de mensajes a través de canales personalizadas que Amazon Pinpoint no admite, como, por ejemplo, las plataformas de redes sociales. Para obtener más información, consulte Creación de canales personalizados en Amazon Pinpoint.

Al invocar un enlace de Lambda mediante Amazon Pinpoint, la función de Lambda también debe estar en la misma región que el proyecto de Amazon Pinpoint.

Para modificar los segmentos de la campaña AWS Lambda, cree primero una función que procese los datos de eventos enviados por Amazon Pinpoint y devuelva un segmento modificado. A continuación, autorice a Amazon Pinpoint a invocar la función asignando una política de función de Lambda. Por último, asigne la función a una o varias campañas definiendo configuraciones de CampaignHook.

Para obtener más ejemplos de código, consulte Ejemplos de código.

Datos de evento

Cuando Amazon Pinpoint invoca la función de Lambda, proporciona la siguiente carga como los datos de eventos:

{
  "MessageConfiguration": {Message configuration}
  "ApplicationId": ApplicationId,
  "CampaignId": CampaignId,
  "TreatmentId": TreatmentId,
  "ActivityId": ActivityId,
  "ScheduledTime": Scheduled Time,
  "Endpoints": {
    EndpointId: {Endpoint definition}
    . . .
  }
}

AWS Lambda pasa los datos del evento al código de la función. Los datos de eventos proporciona los siguientes atributos:

• MessageConfiguration: tiene la misma estructura que el objeto DirectMessageConfiguration del recurso de mensajes en la API de Amazon Pinpoint.

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

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

• TreatmentId: el ID de una variación de campaña utilizada para efectuar pruebas A/B.

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

• ScheduledTime: la fecha y hora, en formato ISO 8601, en que se enviarán los mensajes de la campaña.

• Endpoints: una asignación que asocia los ID de los puntos de conexión con las definiciones de estos últimos. Cada carga de datos de eventos contiene hasta 50 puntos de enlace. Si el segmento de 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.

Creación de una función de Lambda

Para obtener información sobre cómo crear una función de Lambda, consulte Introducción en la Guía para desarrolladores de AWS Lambda . Al crear la función, recuerde que la entrega de mensajes produce un error en las siguientes condiciones:

• La función de Lambda tarda más de 15 segundos en devolver el segmento modificado.

• Amazon Pinpoint no puede decodificar el valor de retorno de la función.

• La función requiere más de 3 intentos de Amazon Pinpoint para invocarla correctamente.

Amazon Pinpoint solo acepta las definiciones de punto de conexión del valor de retorno de la función. La función no puede modificar otros elementos de los datos de eventos.

Ejemplo de función de Lambda

La función de Lambda procesa los datos de eventos enviados por Amazon Pinpoint y devuelve los puntos de conexión modificados, tal y como se muestra en el siguiente controlador de ejemplo, escrito en Node.js:

'use strict';
 
exports.handler = (event, context, callback) => {
    for (var key in event.Endpoints) {
        if (event.Endpoints.hasOwnProperty(key)) {
            var endpoint = event.Endpoints[key];
            var attr = endpoint.Attributes;
            if (!attr) {
                attr = {};
                endpoint.Attributes = attr;
            }
            attr["CreditScore"] = [ Math.floor(Math.random() * 200) + 650];
        }
    }
    console.log("Received event:", JSON.stringify(event, null, 2));
    callback(null, event.Endpoints);
};

Lambda transfiere los datos de eventos al controlador según el parámetro event.

En este ejemplo, el controlador itera mediante cada punto de enlace en el objeto event.Endpoints y añade un nuevo atributo, CreditScore, en el punto de enlace. El valor del atributo CreditScore es simplemente un número aleatorio.

La console.log() declaración registra el evento en CloudWatch Logs.

La instrucción callback() devuelve los puntos de conexión modificados a Amazon Pinpoint. Normalmente, el parámetro callback es opcional en las funciones de Lambda de Node.js, pero es obligatorio en este contexto porque la función debe devolver los puntos de conexión actualizados a Amazon Pinpoint.

Su función debe devolver los puntos de enlace en el mismo formato proporcionado por los datos de eventos, que es un mapa que asocia los ID de punto de enlace con las definiciones de punto de enlace, como en el siguiente ejemplo:

{
    "eqmj8wpxszeqy/b3vch04sn41yw": {
        "ChannelType": "GCM",
        "Address": "4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c",
        "EndpointStatus": "ACTIVE",
        "OptOut": "NONE",
        "Demographic": {
            "Make": "android"
        },
        "EffectiveDate": "2017-11-02T21:26:48.598Z",
        "User": {}
    },
    "idrexqqtn8sbwfex0ouscod0yto": {
        "ChannelType": "APNS",
        "Address": "1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f",
        "EndpointStatus": "ACTIVE",
        "OptOut": "NONE",
        "Demographic": {
            "Make": "apple"
        },
        "EffectiveDate": "2017-11-02T21:26:48.598Z",
        "User": {}
    }
}

La función de ejemplo modifica y devuelve el objeto event.Endpoints que recibió en los datos de evento.

Si lo prefiere, puede incluir los atributos BodyOverride y TitleOverride en las definiciones de los puntos de enlace que se devuelven.

nota

Cuando se utiliza esta solución para enviar mensajes, Amazon Pinpoint solo respeta los atributos TitleOverride y BodyOverride de los puntos de conexión cuando el valor del atributo ChannelType es uno de los siguientes: ADM, APNS, APNS_SANDBOX, APNS_VOIP, APNS_VOIP_SANDBOX, BAIDU, GCM o SMS.

Amazon Pinpoint no respeta estos atributos de los puntos de conexión cuando el valor del atributo ChannelType es EMAIL.

Asignación de una política de función de Lambda

Antes de poder utilizar la función de Lambda para procesar los puntos de conexión, debe autorizar a Amazon Pinpoint a invocar la función de Lambda. Para conceder permiso de invocación, asigne una política de función de Lambda a la función. Una política de función de Lambda consiste en una política de permisos basada en el recurso que designa qué entidades pueden usar la función y qué acciones pueden realizar dichas entidades.

Para obtener más información, consulte Uso de políticas basadas en recursos para AWS Lambda en la Guía del desarrollador de AWS Lambda .

Política de función de ejemplo

La siguiente política concede permiso a la entidad principal del servicio de Amazon Pinpoint para utilizar la acción lambda:InvokeFunction para una campaña específica (campaign-id):

{
  "Sid": "sid",
  "Effect": "Allow",
  "Principal": {
    "Service": "pinpoint.us-east-1.amazonaws.com"
  },
  "Action": "lambda:InvokeFunction",
  "Resource": "{arn:aws:lambda:us-east-1:account-id:function:function-name}",
  "Condition": {
    "StringEquals": {
      "AWS:SourceAccount": "111122223333"
    },
    "ArnLike": {
      "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/campaign-id"
    }
  }
}

La política de función requiere un bloque Condition que incluye una clave AWS:SourceArn. Este código indica qué campaña de Amazon Pinpoint tiene permitido invocar la función. En este ejemplo, la política concede permiso solo a una única campaña. El Condition bloque también debe incluir una AWS:SourceAccount clave que controle qué AWS cuenta puede invocar la acción.

Para escribir una política más genérica, use caracteres comodín (*) que sustituyan a varios caracteres. Por ejemplo, puede usar el siguiente bloque Condition para permitir que cualquier campaña en un proyecto (application-id) concreto de Amazon Pinpoint invoque la función:

...
"Condition": {
  "StringEquals": {
    "AWS:SourceAccount": "111122223333"
  },
  "ArnLike": {
    "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/*"
  }
}
...

Si desea que la función de Lambda sea la función predeterminada que utilizan todas las campañas de un proyecto, le recomendamos que configure el bloque Condition para la política de la forma anterior. Para obtener información sobre la configuración de una función de Lambda como predeterminada para todas las campañas de un proyecto, consulte Asignación de una función de Lambda a una campaña.

Concesión del permiso de invocación de Amazon Pinpoint

Puede usar AWS Command Line Interface (AWS CLI) para añadir permisos a la política de funciones de Lambda asignada a su función de Lambda. Para permitir que Amazon Pinpoint invoque una función para una campaña específica, use el comando add-permission de Lambda, como se muestra en el siguiente ejemplo:

$ aws lambda add-permission \
> --function-name function-name \
> --statement-id sid \
> --action lambda:InvokeFunction \
> --principal pinpoint.us-east-1.amazonaws.com \
> --source-account 111122223333
> --source-arn arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/campaign-id

Puede buscar los ID de la campaña mediante el comando get-campaigns en la AWS CLI. También puede buscar el ID de la aplicación mediante el comando get-apps.

Cuando ejecuta el comando add-permission de Lambda, 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:function-name\",
    \"Condition\":
      {\"ArnLike\":
        {\"AWS:SourceArn\":
         \"arn:aws:mobiletargeting:us-east-1:111122223333:apps/application-id/campaigns/campaign-id\"}}
      {\"StringEquals\": 
        {\"AWS:SourceAccount\": 
          \"111122223333\"}}}
}

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

Asignación de una función de Lambda a una campaña

Puede asignar una función de Lambda a una campaña de Amazon Pinpoint individual. O bien, puede configurar la función de Lambda como la predeterminada que utilizan todas las campañas de un proyecto, excepto en el caso de las campañas a las que se le asigne una función de manera individual.

Para asignar una función de Lambda a una campaña individual, use la API de Amazon Pinpoint a fin de crear o actualizar un objeto Campaign y defina su atributo CampaignHook. Para establecer una función de Lambda como la predeterminada de todas las campañas de un proyecto, cree o actualice el recurso Settings de ese proyecto y defina su objeto CampaignHook.

En ambos casos, establezca los siguientes atributos CampaignHook:

• LambdaFunctionName: el nombre o ARN de la función de Lambda que Amazon Pinpoint invoca antes de enviar mensajes para la campaña.

• Mode: se establece en FILTER. Con este modo, Amazon Pinpoint invoca la función y espera a que devuelva los puntos de conexión modificados. Tras recibirlos, Amazon Pinpoint envía el mensaje. Amazon Pinpoint espera hasta 15 segundos antes de que se produzca un error en el envío del mensaje.

Con la configuración de CampaignHook definida para una campaña, Amazon Pinpoint invoca la función de Lambda especificada antes de enviar los mensajes de la campaña. Amazon Pinpoint espera a recibir los puntos de conexión modificados de la función. Si Amazon Pinpoint recibe los puntos de conexión actualizados, continúa con el envío de mensajes, mediante los datos de punto de conexión actualizados.