Importar segmentos

Com o Amazon Pinpoint, você pode definir um segmento de usuário importando um arquivo que contém informações sobre os usuários que pertencem ao segmento. A importação de segmentos é útil se você define segmentos de usuários fora do Amazon Pinpoint, mas deseja envolver os usuários em campanhas do Amazon Pinpoint.

Ao contrário de segmentos dinâmicos feitos com o criador de segmentos no console, um segmento importado corresponde a um conjunto fixo de endpoints ou IDs de usuário:

Endpoint

Um destino para o qual é possível enviar mensagens, como um endereço de e-mail, um identificador de dispositivo móvel ou um número de telefone celular. A definição de um endpoint pode incluir atributos que descrevem o usuário ou o dispositivo para o qual você envia as mensagens. Ele também pode incluir um ID de usuário.

Você pode definir um segmento importando uma lista de definições de endpoints. O Amazon Pinpoint cria o segmento e atualiza todos os endpoints que você adicionou anteriormente ao Amazon Pinpoint com as novas informações.

ID de usuário

Um ID que representa um usuário individual em seu público. Esse ID deve ser atribuído a um ou mais endpoints. Por exemplo, se uma pessoa usar o aplicativo em mais de um dispositivo, o aplicativo poderá atribuir o ID de usuário dessa pessoa ao endpoint de cada dispositivo.

Você poderá definir um segmento por meio da importação de IDs de usuários apenas se tiver adicionado os endpoints associados aos IDs de usuários ao Amazon Pinpoint.

Um segmento importado é composto de endpoints, IDs de usuário ou uma combinação de ambos. Quando você usa o Amazon Pinpoint para enviar uma mensagem ao segmento, os possíveis destinos incluem:

• Cada endpoint que você listar no arquivo importado.

• Cada endpoint associado a cada um dos IDs de usuário que você listar no arquivo importado.

Ao criar um novo segmento, você pode usar um segmento importado como base. Em seguida, você pode aplicar filtros para o segmento base para refinar-lo de acordo com suas necessidades.

Considerações sobre segmentos importados

Considere os seguintes fatores ao criar segmentos importados:

• Ao criar uma campanha, você precisa escolher um segmento. Quando você escolhe um segmento dinâmico, o Amazon Pinpoint fornece uma estimativa do tamanho do segmento. No entanto, quando você escolhe um segmento importado, o Amazon Pinpoint não pode fornecer uma estimativa.

• Se você criar uma campanha que envia mensagens quando determinados eventos ocorrem, não poderá usar segmentos importados. As campanhas com base em eventos só podem usar segmentos dinâmicos. Para obter mais informações sobre como criar segmentos dinâmicos, consulte Criar segmentos.

Arquivos de segmentos

Defina os endpoints ou IDs de usuário que pertencem ao segmento em um arquivo CSV (valores separados por vírgula) ou JSON. Em seguida, importe o arquivo para o Amazon Pinpoint para criar o segmento.

Ao importar um segmento, lembre-se do seguinte:

• O Amazon Pinpoint não pode importar arquivos compactados.

• Os arquivos importados devem usar a codificação de caracteres UTF-8.

• Se estiver importando novos endpoints, os atributos Address e ChannelType serão necessários.

• Se estiver atualizando endpoints existentes, o atributo Id será necessário para cada endpoint que deseja atualizar.

• As definições de endpoint podem incluir somente determinados atributos. Para ver uma lista, consulte Atributos compatíveis. Além disso, um nome de atributo deve ter no máximo 50 caracteres. Um valor de atributo deve ter no máximo 100 caracteres.

Exemplo de arquivos de segmento

Os arquivos de exemplo nesta seção são baseados nos seguintes dados:

Exemplo de valores de atributos de endpoint
ChannelType	Endereço	Location.Country	Demographic.Platform	Demographic.Make	Usuário. UserId
SMS	[phone]	CA	Android	LG	example-user-id-1
APNS	1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f	EUA	iOS	Apple	example-user-id-2
EMAIL	[e-mail]	EUA	iOS	Apple	example-user-id-2
GCM	4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c	CN	Android	Google	example-user-id-3
EMAIL	[e-mail]	CN	Android	OnePlus	example-user-id-3

Cada linha na tabela representa um único endpoint. Os IDs de usuário example-user-id-2 e example-user-id-3 são atribuídos a dois endpoints cada.

exemplo Arquivo com definições de endpoint

CSV

Você pode importar endpoints definidos em um arquivo CSV, como no exemplo a seguir:

ChannelType,Address,Location.Country,Demographic.Platform,Demographic.Make,User.UserId
SMS,[phone],CA,Android,LG,example-user-id-1
APNS,1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f,US,iOS,Apple,example-user-id-2
EMAIL,[e-mail],US,iOS,Apple,example-user-id-2
GCM,4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c,CN,Android,Google,example-user-id-3
EMAIL,[e-mail],CN,Android,OnePlus,example-user-id-3

A primeira linha é o cabeçalho, que contém os atributos de endpoint. Para obter uma lista completa de atributos possíveis, consulte Atributos compatíveis.

As linhas seguintes definem os endpoints ao dar valores para cada atributo no cabeçalho.

Para incluir uma vírgula ou aspas em um valor, coloque o valor desejado entre aspas, como em "aaa,bbb".

O arquivo CSV não pode conter quebras de linha ou tabulações. Se o arquivo contiver dados com quebras de linha ou tabulações, os dados no arquivo podem não ser importados ou o processo de importação pode falhar.

JSON

Você pode importar os endpoints que estão definidos em um arquivo JSON delimitado por novas linhas. Nesse formato, cada linha é um objeto JSON completo que contém uma definição de endpoint individual, como no exemplo a seguir:

{"ChannelType":"SMS","Address":"[phone]","Location":{"Country":"CA"},"Demographic":{"Platform":"Android","Make":"LG"},"User":{"UserId":"example-user-id-1"}}
{"ChannelType":"APNS","Address":"1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f","Location":{"Country":"US"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}}
{"ChannelType":"EMAIL","Address":"[e-mail]","Location":{"Country":"US"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}}
{"ChannelType":"GCM","Address":"4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c","Location":{"Country":"CN"},"Demographic":{"Platform":"Android","Make":"Google"},"User":{"UserId":"example-user-id-3"}}
{"ChannelType":"EMAIL","Address":"[e-mail]","Location":{"Country":"CN"},"Demographic":{"Platform":"Android","Make":"OnePlus"},"User":{"UserId":"example-user-id-3"}}

Para obter uma lista completa de atributos possíveis, consulte Atributos compatíveis.

Importar um segmento

Há duas maneiras de importar segmentos para o Amazon Pinpoint: você pode fazer upload de arquivos diretamente do seu computador ou importar arquivos armazenados em um bucket do Amazon S3.

Fazer upload de arquivos do seu computador geralmente é o método mais fácil de importação de segmentos, especialmente se você já tem os dados do cliente no computador. No entanto, só é possível importar 10 arquivos por vez e fazer upload de arquivos com menos de 1 gigabyte (GB).

Se você precisar importar mais de 10 arquivos de uma só vez ou fazer upload de arquivos com mais de 1 GB, importe os arquivos do Amazon S3. A opção de importação do Amazon S3 também será útil se você já tiver processos que enviam arquivos de dados do cliente para o Amazon S3 para armazenamento.

Esta seção inclui procedimentos para importar segmentos usando os dois métodos.

Importar um segmento pelo upload de um arquivo no computador

Você pode criar segmentos fazendo upload de até 10 arquivos diretamente do computador. Os arquivos do qual você faz upload podem estar no formato JSON ou CSV. É possível fazer upload de arquivos em qualquer combinação de formatos. Por exemplo, você pode fazer upload de um arquivo JSON e três arquivos CSV.

Para importar um segmento

1. Faça login no console do Amazon Pinpoint em https://console.aws.amazon.com/pinpoint/.

2. Na página All projects (Todos os projetos), selecione o projeto ao qual você deseja adicionar o segmento.

3. No painel de navegação, selecione Segmentos.

4. Selecione Criar um segmento.

5. Em Create a segment (Criar um segmento), escolha Import a segment (Importar um segmento).

6. Em Import method (Método de importação), escolha Upload files from your computer (Fazer upload de arquivos do computador).

7. Em Files to import (Arquivos para importar), selecione Choose files (Escolher arquivos). Selecione o arquivo ou os arquivos que você deseja importar.

   nota

   Você também pode arrastar arquivos do explorador de arquivos do computador e soltá-los diretamente na área Drop files here (Soltar arquivos aqui).

8. Ao fazer upload de arquivos para o Amazon Pinpoint, você precisa fornecer um nome de segmento para cada arquivo importado. Em Nomes de segmentos, insira um nome de segmento para cada arquivo que você deseja importar.

   Por padrão, o Amazon Pinpoint fornece um nome de segmento igual ao nome do arquivo importado, mas sem a extensão do nome de arquivo. É possível alterar esses valores padrão para qualquer nome.

   

   nota

   Você pode usar o mesmo nome para vários segmentos. Se fizer isso, o Amazon Pinpoint criará um segmento diferente para cada arquivo e atribuirá um ID exclusivo a cada um deles. A data de criação também é um pouco diferente para cada arquivo que você importar. Você pode usar esses fatores para distinguir entre segmentos com o mesmo nome.

9. Ao concluir, selecione Create Bucket (Criar bucket).

Importar um segmento de um arquivo armazenado no Amazon S3

Antes de usar este procedimento para importar um segmento, é necessário primeiro criar um bucket do Amazon S3 e fazer upload do arquivo para esse bucket. Você pode organizar os arquivos de segmentos diferentes em pastas separadas. Quando o Amazon Pinpoint importa os endpoints ou os IDs de usuários de um segmento, ele inclui os arquivos em todas as pastas e subpastas pertencentes ao local do Amazon S3 especificado.

Para uma introdução à criação de buckets e ao upload de objetos, consulte o artigo O que é o Amazon S3? no Guia do usuário do Amazon Simple Storage Service.

O Amazon Pinpoint pode importar apenas um formato de arquivo (CSV ou JSON) por segmento, portanto, o caminho do Amazon S3 especificado deve conter apenas arquivos de um único tipo.

Para importar um segmento

1. Faça login no console do Amazon Pinpoint em https://console.aws.amazon.com/pinpoint/.

2. Na página All projects (Todos os projetos), selecione o projeto ao qual você deseja adicionar o segmento.

3. No painel de navegação, selecione Segmentos.

4. Selecione Criar um segmento.

5. Em Create a segment (Criar um segmento), escolha Import a segment (Importar um segmento).

6. Em Segment name (Nome do segmento), digite um nome para o segmento que facilite seu reconhecimento posteriormente.

7. Em URL do Amazon S3, digite o local do bucket do Amazon S3 que contém o arquivo do segmento. O endereço do bucket precisa estar no seguinte formato:

   s3://bucket-name/folder-name

   O Amazon Pinpoint importa os arquivos do caminho especificado e de qualquer subpasta nesse caminho.

8. Em perfil do IAM, realize uma das etapas a seguir:

   • Se você quiser que o Amazon Pinpoint crie um perfil que permita que ele leia a partir de um bucket do Amazon S3, selecione Criar automaticamente um perfil. Depois, em Perfil do IAM, digite um nome para a função que você está criando.

   • Se você já tiver criado um perfil do IAM que permite que o Amazon Pinpoint leia a partir de um bucket do Amazon S3, selecione Escolher uma função existente. Em seguida, em Perfil do IAM, escolha um perfil que contenha as permissões apropriadas.

   Se você deseja criar o perfil do IAM por conta própria, consulte Perfil do IAM para importar endpoints ou segmentos no Guia do desenvolvedor do Amazon Pinpoint. Depois de criar o perfil, especifique-o no console do Amazon Pinpoint.

9. Em Que tipo de arquivo você está importando, escolha JavaScript Object Notation (JSON) ou Comma-Separated Values (CSV), dependendo do formato do arquivo que você carregou no Amazon S3.

10. Selecione Criar um segmento.

Atributos compatíveis

A tabela nesta seção lista e descreve os atributos que você pode especificar nas definições de endpoint que importa para o Amazon Pinpoint. Se você importar segmentos usando arquivos CSV, os cabeçalhos no arquivo deverão corresponder aos nomes exibidos na coluna Atributo.

Para arquivos JSON, um ponto no nome do atributo indica que o nome após o ponto é um objeto que está aninhado em um objeto pai com um nome igual ao valor antes do ponto. Por exemplo, um arquivo JSON que contém os atributos Demographic.Make e Demographic.Model tem a seguinte estrutura:

{
...
"Demographic": {
  ...
  "Make":"Apple",
  "Model":"iPhone"
  ...
  }
...
}

A estrutura JSON completa lembra muito o exemplo de solicitação de endpoint na Referência da API do Amazon Pinpoint. No entanto, nem todos os atributos no esquema de solicitação de endpoint são compatíveis quando você importa os segmentos, incluindo o EndpointStatus e o EffectiveDate.

Para que um campo personalizado tenha vários valores em CSV, você precisa replicar o cabeçalho e manter um valor por cabeçalho. Por exemplo: .

...,User.UserId, User.UserAttributes.new_multi_field,User.UserAttributes.new_multi_field
...,example-user-id-2,test10,test20

É possível substituir os nomes de atributos exibidos em como custom_attribute por qualquer valor. Por exemplo, se você deseja armazenar o nome e o sobrenome dos usuários em atributos chamados FirstName e LastName, pode criar atributos personalizados chamados User.UserAttributes.FirstName e User.UserAttributes.LastName, respectivamente. Um nome de atributo pode conter até 50 caracteres. Um valor de atributo pode conter até 100 caracteres. Os nomes dos atributos diferenciam maiúsculas de minúsculas.

Em JSON, o atributo personalizado precisa ser formatado em "Attributes":{"Ride":["Bus"]}.

Atributo	Descrição
Address	O endereço de destino exclusivo para mensagens ou notificações por push enviadas para o endpoint, por exemplo, um endereço de e-mail, um número de telefone ou um token de dispositivo. nota Se o endereço do endpoint for um número de telefone, você deverá especificá-lo no formato E.164. Para obter mais informações sobre o formato E.164, consulte E.164 na Wikipédia.
Attributes.custom_attribute	Um atributo personalizado que descreve o endpoint. É possível usar esse tipo de atributo como um critério de seleção ao criar um segmento. Você pode substituir custom_attribute por qualquer valor.
ChannelType	O canal a ser usado ao enviar mensagens ou notificações por push para o endpoint. Por exemplo: . APNS: para um endpoint que pode receber notificações por push enviadas através do canal Apple Push Notification service (APNs) para aplicativos em execução em dispositivos iOS. EMAIL: para um endpoint que possa receber mensagens de e-mail. GCM: para um endpoint que possa receber notificações por push enviadas através do canal Firebase Cloud Messaging (FCM) para aplicativos em execução em dispositivos Android. SMS: para um endpoint que possa receber mensagens de texto SMS.
Demographic.AppVersion	O número da versão do aplicativo que está associado ao endpoint.
Demographic.Locale	A região do endpoint, no seguinte formato: o código ISO 639-1 alfa-2 seguido por um sublinhado (_), seguido por um valor ISO 3166-1 alfa-2 . Por exemplo, en_US é a região do idioma Inglês para os Estados Unidos.
Demographic.Make	O fabricante do dispositivo de endpoint, como apple ou samsung.
Demographic.Model	O nome do modelo ou número do dispositivo do endpoint, como iPhone ou SM-G900F.
Demographic.ModelVersion	A versão do modelo do dispositivo de endpoint.
Demographic.Platform	O sistema operacional do dispositivo do endpoint, como ios ou android.
Demographic.PlatformVersion	A versão do sistema operacional do dispositivo do endpoint.
Demographic.Timezone	O fuso horário do endpoint, como um valor de banco de dados tz. Por exemplo, America/Los_Angeles para o horário do Pacífico (América do Norte). nota Os seguintes fusos horários não são mais compatíveis e são automaticamente redirecionados para os fusos horários compatíveis. Fuso horário Fuso horário redirecionado Canada/East-Saskatchewan America/Managua US/Pacific-New America/Los_Angeles
EffectiveDate	A data e a hora em que o endpoint foi atualizado pela última vez, no formato ISO 8601. Por exemplo, 2019-08-23T10:54:35.220Z para 10:54 UTC 23 de agosto de 2019.
Id	Um identificador exclusivo do endpoint.
Location.City	A cidade onde o endpoint está localizado.
Location.Country	O código de três letras no formato ISO 3166-1 alpha-2 do país ou região onde o endpoint está localizado. Por exemplo, US para os Estados Unidos.
Location.Latitude	A coordenada de latitude da localização do endpoint, arredondada para uma casa decimal.
Location.Longitude	A coordenada de longitude da localização do endpoint, arredondada para uma casa decimal.
Location.PostalCode	O código postal ou CEP para a área onde o endpoint está localizado.
Location.Region	O nome da região, como o estado ou a província onde o endpoint está localizado.
Metrics.custom_attribute	Uma métrica numérica personalizada que seu aplicativo reporta ao Amazon Pinpoint para o endpoint. por exemplo, o número de sessões ou o número de itens deixados em um carrinho, para usar para fins de segmentação. Você pode substituir custom_attribute por qualquer valor. Esses valores personalizados podem ser somente numéricos. Por serem numéricos, o Amazon Pinpoint pode realizar operações aritméticas com eles, como média ou soma.
OptOut	Indica se um usuário optou por não receber mensagens e notificações por push de você. Os valores aceitáveis são: ALL, o usuário optou por não receber mensagens nem notificações por push; ou NONE, o usuário deseja receber todas as mensagens e notificações por push.
RequestId	O identificador exclusivo da solicitação mais recente de atualização do endpoint.
User.UserAttributes.custom_attribute	Um atributo personalizado que descreve o usuário. Você pode substituir custom_attribute por qualquer valor, como FirstName ou Age.
User.UserId	Um identificador exclusivo para o usuário.

É possível criar até 250 atributos personalizados para endpoints e usuários em cada projeto. Para obter mais informações, consulte Cotas do Amazon Pinpoint no Guia do desenvolvedor do Amazon Pinpoint.