Personalização de segmentos com AWS Lambda

Essa documentação é de pré-lançamento para um atributo em versão beta pública. Está sujeita a alteração.

Você pode usar AWS Lambda para personalizar a forma como uma campanha do Amazon Pinpoint envolve seu público-alvo. Com AWS Lambda, você pode modificar o segmento da campanha no momento em que o Amazon Pinpoint envia a mensagem da campanha.

AWS Lambda é um serviço de computação que você pode usar para executar código sem provisionar ou gerenciar servidores. Você empacota seu código e faz upload no Lambda como funções do Lambda. O Lambda executa uma função quando ela é invocada, o que pode ser feito manualmente por você ou automaticamente em resposta a eventos. Para mais informações, consulte o Guia do desenvolvedor do AWS Lambda.

Para atribuir uma função do Lambda a uma campanha, defina as configurações CampaignHook da campanha usando o recurso Campanha na API do Amazon Pinpoint. Essas configurações incluem o nome da função do Lambda. Elas também incluem o modo CampaignHook que define se o Amazon Pinpoint recebe um valor de retorno da função.

Uma função do Lambda que você atribui a uma campanha é referida como uma extensão do Amazon Pinpoint.

Com as configurações de CampaignHook definidas, o Amazon Pinpoint invoca automaticamente a função do Lambda ao executar a campanha, antes de enviar a mensagem da campanha. Quando o Amazon Pinpoint invoca a função, ele fornece dados de eventos sobre a entrega da mensagem. Esses dados incluem o segmento da campanha, que é a lista de endpoints aos quais o Amazon Pinpoint envia a mensagem.

Se o modo CampaignHook estiver definido como FILTER, o Amazon Pinpoint permite que a função modifique e retorne o segmento antes de enviar a mensagem. Por exemplo, a função pode atualizar as definições de endpoint com atributos que contenham dados de uma origem externa ao Amazon Pinpoint. Ou a função pode filtrar o segmento removendo determinados endpoints, com base em condições no código da função. Depois de o Amazon Pinpoint receber o segmento modificado da função, ele envia a mensagem para cada um dos endpoints do segmento usando o canal de entrega da campanha.

Ao processar seus segmentos com AWS Lambda, você tem mais controle sobre para quem envia mensagens e o que essas mensagens contêm. Você pode personalizar suas campanhas em tempo real, no momento em que as mensagens da campanha são enviadas. A filtragem de segmentos permite que você envolva subconjuntos de segmentos definidos de maneira mais restrita. Adicionar ou atualizar os atributos do endpoint permite que você disponibilize novos dados para variáveis de mensagens.

nota

Você também pode usar as configurações de CampaignHook para atribuir uma função do Lambda que lide com a entrega de mensagens. Esse tipo de função é útil para a entrega de mensagens por meio de canais personalizados aos quais o Amazon Pinpoint não oferece suporte, como plataformas de mídia social. Para ter mais informações, consulte Criação de canais personalizados no Amazon Pinpoint.

Ao invocar um hook do Lambda usando o Amazon Pinpoint, a função do Lambda também deve estar na mesma região do projeto do Amazon Pinpoint.

Para modificar segmentos de campanha com AWS Lambda, primeiro crie uma função que processe os dados do evento enviados pelo Amazon Pinpoint e retorne um segmento modificado. Em seguida, autorize o Amazon Pinpoint a invocar a função atribuindo uma política de função do Lambda. Por fim, atribua a função a uma ou mais campanhas, definindo as configurações CampaignHook.

Para ver mais exemplos de código, consulte Exemplos de código.

Dados de eventos

Quando o Amazon Pinpoint invoca a função do Lambda, ele fornece a carga a seguir como dados de eventos:

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

AWS Lambda passa os dados do evento para o código da função. Os dados de eventos fornecem os seguintes atributos:

• MessageConfiguration: tem a mesma estrutura do objeto DirectMessageConfiguration do recurso Mensagens na API do Amazon Pinpoint.

• ApplicationId: o ID do projeto do Amazon Pinpoint ao qual a campanha pertence.

• CampaignId: o ID da campanha do Amazon Pinpoint para o qual a função é invocada.

• TreatmentId: o ID de uma variação de campanha usada para testes A/B.

• ActivityId: o ID da atividade sendo executada pela campanha.

• ScheduledTime: a data e o horário, em formato ISO 8601, em que as mensagens da campanha serão entregues.

• Endpoints: um mapa que associa IDs de endpoint a definições de endpoint. Cada carga de dados de eventos contém até 50 endpoints. Se o segmento da campanha contiver mais de 50 endpoints, o Amazon Pinpoint invocará a função repetidamente, com até 50 endpoints por vez, até que todos os endpoints sejam processados.

Criação de uma função do Lambda

Para saber como criar uma função do Lambda, consulte Conceitos básicos no Guia do desenvolvedor do AWS Lambda . Ao criar a função, lembre-se de que a entrega de mensagens falha nas seguintes condições:

• A função do Lambda leva mais de 15 segundos para retornar o segmento modificado.

• O Amazon Pinpoint não consegue decodificar o valor de retorno da função.

• A função requer mais de 3 tentativas do Amazon Pinpoint para invocá-lo com êxito.

O Amazon Pinpoint só aceita definições de endpoint no valor de retorno da função. A função não consegue modificar outros elementos nos dados de eventos.

Exemplo de função do Lambda

Sua função do Lambda processa os dados de eventos enviados pelo Amazon Pinpoint e retorna os endpoints modificados, conforme mostrado pelo seguinte handler de exemplo, escrito em 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);
};

O Lambda passa os dados de eventos para o handler como o parâmetro event.

Neste exemplo, o handler percorre cada endpoint no objeto event.Endpoints e adiciona um novo atributo, CreditScore, ao endpoint. O valor do atributo CreditScore é simplesmente um número aleatório.

A console.log() declaração registra o evento em CloudWatch Logs.

A instrução callback() retorna os endpoints modificados ao Amazon Pinpoint. Normalmente, o parâmetro callback é opcional em funções do Lambda Node.js, mas é necessário neste contexto porque a função deve retornar os endpoints atualizados ao Amazon Pinpoint.

Sua função deve retornar endpoints no mesmo formato fornecido pelos dados do evento, que é um mapa que associa IDs de endpoint a definições de endpoint, como no exemplo a seguir:

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

A função de exemplo modifica e retorna o objeto event.Endpoints que recebeu nos dados do evento.

Opcionalmente, você pode incluir os atributos BodyOverride e TitleOverride nas definições de endpoint que retorna.

nota

Quando você usa essa solução para enviar mensagens, o Amazon Pinpoint respeita os atributos TitleOverride e BodyOverride apenas para endpoints em que o valor do atributo ChannelType é um dos seguintes: ADM, APNS, APNS_SANDBOX, APNS_VOIP, APNS_VOIP_SANDBOX, BAIDU, GCM ou SMS.

O Amazon Pinpoint não respeita esses atributos para endpoints em que o valor do atributo ChannelType é EMAIL.

Atribuir uma política de função do Lambda

Para usar a função do Lambda para processar endpoints, você deve primeiro autorizar o Amazon Pinpoint a invocar essa função. Para conceder permissão de invocação, atribua uma política de função do Lambda à função. A política de função do Lambda é uma política de permissões com base em recursos que designa as entidades que podem usar sua função e que ações essas entidades podem executar.

Para mais informações, consulte Uso de políticas com base em recursos para o AWS Lambda no Guia do usuário do AWS Lambda .

Exemplo de política de função

A política a seguir concede permissão à entidade principal de serviço do Amazon Pinpoint para usar a ação lambda:InvokeFunction para uma campanha 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"
    }
  }
}

Sua política de função requer um bloco Condition que inclua uma chave AWS:SourceArn. Esse código informa que a campanha do Amazon Pinpoint tem permissão para invocar a função. Neste exemplo, a política concede permissão apenas a uma única campanha. O Condition bloco também deve incluir uma AWS:SourceAccount chave, que controla qual AWS conta pode invocar a ação.

Para escrever uma política mais genérica, use um curinga que corresponda a vários caracteres (*). Por exemplo, você pode usar o seguinte bloco Condition para permitir que qualquer campanha em um projeto específico do Amazon Pinpoint (application-id) chame a função:

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

Para que a função do Lambda seja a função padrão usada por todas as campanhas de um projeto, recomendamos configurar o bloco Condition para a política da maneira anterior. Para obter informações sobre como definir uma função do Lambda como padrão para todas as campanhas em um projeto, consulte Atribuição de uma função do Lambda a uma campanha.

Conceder permissão de invocação do Amazon Pinpoint

Você pode usar o AWS Command Line Interface (AWS CLI) para adicionar permissões à política de função do Lambda atribuída à sua função do Lambda. Para permitir que o Amazon Pinpoint invoque uma função para uma campanha específica, use o comando do Lambda add-permission, conforme mostrado no exemplo a seguir:

$ 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

Você pode pesquisar seus IDs de campanha usando o comando get-campaigns no. AWS CLI. Você também pode pesquisar o ID do seu aplicativo usando o comando get-apps.

Ao executar o comando add-permission do Lambda, o Lambda retornará o seguinte resultado:

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

O valor de Statement é uma versão da cadeia de caracteres JSON da instrução adicionada à política da função do Lambda.

Atribuição de uma função do Lambda a uma campanha

Você pode atribuir uma função do Lambda a uma campanha do Amazon Pinpoint específica. Ou é possível definir a função do Lambda como o padrão usado por todas as campanhas de um projeto, exceto nas campanhas para as quais você atribui uma função individualmente.

Para atribuir uma função do Lambda a uma campanha específica, use a API do Amazon Pinpoint para criar ou atualizar um objeto Campaign e definir seu atributo CampaignHook. Para definir uma função do Lambda como padrão para todas as campanhas em um projeto, crie ou atualize o recurso Settings para esse projeto e defina seu objeto CampaignHook.

Em ambos os casos, defina os seguintes atributos CampaignHook:

• LambdaFunctionName: o nome ou ARN da função do Lambda que o Amazon Pinpoint invoca antes de enviar mensagens para a campanha.

• Mode: defina como FILTER. Com esse modo, o Amazon Pinpoint invoca a função e aguarda até que ela retorne os endpoints modificados. Após recebê-los, o Amazon Pinpoint envia a mensagem. O Amazon Pinpoint aguarda até 15 segundos antes de falhar na entrega da mensagem.

Com as configurações CampaignHook definidas para uma campanha, o Amazon Pinpoint invoca a função do Lambda especificada antes de enviar as mensagens da campanha. O Amazon Pinpoint aguarda o recebimento dos endpoints modificados da função. Se o Amazon Pinpoint recebe os endpoints atualizados, ele prossegue com a entrega da mensagem, usando os dados dos endpoints atualizados.