Fazer uma chamada à API de conteúdo conectado

Use o Connected Content para inserir qualquer informação acessível pela API diretamente nas mensagens enviadas aos usuários. Você pode extrair conteúdo diretamente de seu servidor da Web ou de APIs acessíveis publicamente.

Esta página aborda como fazer chamadas à Connected Content API, casos de uso avançados da Connected Content, tratamento de erros e muito mais.

Envio de uma chamada de Connected Content

Para enviar uma chamada de conteúdo conectado, use a tag {% connected_content %}. Com essa tag, você pode atribuir ou declarar variáveis usando :save. Os aspectos dessas variáveis podem ser referenciados posteriormente na mensagem com Liquid.

Por exemplo, o corpo da mensagem a seguir acessará o URL http://numbersapi.com/random/trivia e incluirá um fato curioso na sua mensagem:

1
2
{% connected_content http://numbersapi.com/random/trivia :save result %}
Hi there, here is some fun trivia for you!: {{result.text}}

Adição de variáveis

Também é possível incluir atribuições de perfil de usuário como variáveis na string de URL ao fazer solicitações de Connected Content.

Por exemplo, você pode ter um serviço da Web que retorna conteúdo com base no endereço de e-mail e no ID de um usuário. Se estiver passando atribuições que contenham caracteres especiais, como o sinal de arroba (@), certifique-se de usar o filtro Liquid url_param_escape para substituir quaisquer caracteres não permitidos em URLs por suas versões escapadas amigáveis ao URL, conforme mostrado no seguinte atributo de endereço de e-mail.

1
2
3
Hi, here are some articles that you might find interesting:

{% connected_content http://www.yourwebsite.com/articles?email={{${email_address} | url_param_escape}}&user_id={{${user_id}}} %}

As solicitações de conteúdo conectado aceitam apenas solicitações GET e POST.

Tratamento de erros

Se o URL não estiver disponível e chegar a uma página 404, a Braze renderizará uma string vazia em seu lugar. Se o URL chegar a uma página HTTP 500 ou 502, ele falhará na lógica de nova tentativa.

Se o ponto de extremidade retornar JSON, você poderá detectar isso verificando se o valor de connected é nulo e, em seguida, abortar condicionalmente a mensagem. A Braze só permite URLs que se comunicam pelas portas 80 (HTTP) e 443 (HTTPS).

Detecção de host não saudável

O Connected Content emprega um mecanismo de detecção de host não saudável para detectar quando o host de destino apresenta uma alta taxa de lentidão ou sobrecarga significativa, resultando em tempos limite, excesso de solicitações ou outros resultados que impedem que o Braze se comunique com sucesso com o endpoint de destino. Ele atua como uma salvaguarda para reduzir a carga desnecessária que pode estar causando dificuldades ao host de destino. Ele também serve para estabilizar a infraestrutura do Braze e manter velocidades rápidas de envio de mensagens.

Se o host de destino apresentar uma alta taxa de lentidão significativa ou sobrecarga, o Braze interromperá temporariamente as solicitações ao host de destino por um minuto, simulando respostas que indiquem a falha. Após um minuto, o Braze examinará a integridade do host usando um pequeno número de solicitações antes de retomar as solicitações em velocidade máxima se o host for considerado íntegro. Se o host ainda não estiver saudável, o Braze aguardará mais um minuto antes de tentar novamente.

Se as solicitações ao host de destino forem interrompidas pelo detector de host não saudável, o Braze continuará a renderizar mensagens e a seguir sua lógica Liquid como se tivesse recebido um código de resposta de erro. Se você quiser garantir que essas solicitações de Connected Content sejam repetidas quando forem interrompidas pelo detector de host não saudável, use a opção :retry. Para saber mais sobre a opção :retry, consulte Tentativas de Connected Content.

Se achar que a detecção de host não saudável pode estar causando problemas, entre em contato com o suporte da Braze.

Permitindo uma performance eficiente

Como o Braze entrega mensagens em uma velocidade muito rápida, certifique-se de que seu servidor possa lidar com milhares de conexões simultâneas para que os servidores não fiquem sobrecarregados ao baixar o conteúdo. Ao usar APIs públicas, confirme que seu uso não violará nenhum limite de frequência que o provedor de API possa empregar. O Braze exige que o tempo de resposta do servidor seja inferior a dois segundos por motivos de performance; se o servidor demorar mais de dois segundos para responder, o conteúdo não será inserido.

Os sistemas Braze podem fazer a mesma chamada à API Connected Content mais de uma vez por destinatário. Isso se deve ao fato de que a Braze pode precisar fazer uma chamada à API Connected Content para renderizar uma carga útil de mensagem, e as cargas úteis de mensagem podem ser renderizadas várias vezes por destinatário para validação, lógica de nova tentativa ou outros fins internos. Seus sistemas devem ser capazes de tolerar que a mesma chamada da Connected Content seja feita mais de uma vez por destinatário.

Coisas para saber

• O Braze não cobra por chamadas de API e não será contabilizado em seu uso de pontos de dados.
• Há um limite de 1 MB para as respostas do Connected Content.
• As chamadas do Connected Content ocorrerão quando a mensagem for enviada, exceto no caso de mensagens no app, que farão essa chamada quando a mensagem for visualizada.
• As chamadas de Connected Content não seguem redirecionamentos.

Tipos de autenticação

Usando a autenticação básica

Se o URL exigir autenticação básica, o Braze poderá armazenar uma credencial de autenticação básica para você usar em sua chamada à API. Você pode gerenciar as credenciais de autenticação básica existentes e adicionar novas credenciais em Settings > Connected Content.

Para adicionar uma nova credencial, selecione Adicionar credencial > Autenticação básica.

Dê um nome à sua credencial e digite o nome de usuário e a senha.

Em seguida, você pode usar essa credencial de autenticação básica em suas chamadas de API fazendo referência ao nome do token:

1
Hi there, here is some fun trivia for you!: {% connected_content https://yourwebsite.com/random/trivia :basic_auth credential_name %}

Uso de autenticação por token

Ao usar o conteúdo conectado na Braze, você poderá descobrir que certas APIs exigem um token em vez de um nome de usuário e senha. O Braze também pode armazenar credenciais que contêm valores de cabeçalho de autenticação de token.

Para adicionar uma credencial que contenha valores de token, selecione Adicionar credencial > Autenticação de token. Em seguida, adicione os pares de valores-chave para seus cabeçalhos de chamada de API e o domínio permitido.

Em seguida, você pode usar essa credencial em suas chamadas de API fazendo referência ao nome da credencial:

1
2
3
4
5
6
7
8
9
{% assign campaign_name="New Year Sale" %}
{% connected_content
     https://api.endpoint.com/your_path
     :method post
     :auth_credentials token_credential_abc
     :body campaign={{campaign_name}}&customer={{${user_id}}}&channel=Braze
     :content_type application/json
     :save publication
%}

Uso de autenticação aberta (OAuth)

Algumas configurações de API exigem a recuperação de um token de acesso que pode ser usado para autenticar o endpoint da API que você deseja acessar.

Etapa 1: Recuperar o token de acesso

O exemplo a seguir ilustra a recuperação e o salvamento de um token de acesso em uma variável de localização, que pode ser usada para autenticar a chamada subsequente à API. Um parâmetro :cache_max_age pode ser adicionado para corresponder ao tempo de validade do token de acesso e reduzir o número de chamadas de saída do conteúdo conectado. Para saber mais, consulte Cache configurável.

1
2
3
4
5
6
7
8
9
10
{% connected_content
     https://your_API_access_token_endpoint_here/
     :method post
     :auth_credentials access_token_credential_abc
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE"
     }
     :cache_max_age 900
     :save token_response
%}

Etapa 2: Autorizar a API usando o token de acesso recuperado

Depois que o token é salvo, ele pode ser modelado dinamicamente na chamada subsequente do Connected Content para autorizar a solicitação:

1
2
3
4
5
6
7
8
9
{% connected_content
     https://your_API_endpoint_here/
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE",
       "Authorization": "{{token_response}}"
     }
     :body key1=value1&key2=value2
     :save response
%}

Edição de credenciais

Você pode editar o nome da credencial para os tipos de autenticação.

• Para autenticação básica, é possível atualizar o nome de usuário e a senha. Note que a senha inserida anteriormente não estará visível.
• Para a autenticação de token, você pode atualizar os pares de valores-chave do cabeçalho e o domínio permitido. Observe que os valores de cabeçalho definidos anteriormente não estarão visíveis.

Lista de permissões de IP de conteúdo conectado

Quando uma mensagem usando Conteúdo Conectado é enviada pelo Braze, os servidores do Braze automaticamente fazem solicitações de rede aos servidores de nossos clientes ou de terceiros para extrair dados. Com a lista de permissões de IP, você pode verificar se as solicitações de Connected Content estão realmente vindo do Braze, adicionando uma camada de segurança.

A Braze enviará solicitações de conteúdo conectado dos seguintes intervalos de IP. Os intervalos listados são automática e dinamicamente adicionados a quaisquer chaves de API que tenham sido aceitas para a listagem de permissões.

A Braze tem um conjunto reservado de IPs usados para todos os serviços, sendo que nem todos estão ativos em um determinado momento. Isso foi projetado para que a Braze possa enviar de um data center diferente ou fazer manutenção, se necessário, sem afetar os clientes. A Braze poderá usar um, um subconjunto ou todos os seguintes IPs listados ao fazer solicitações de conteúdo conectado.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)

User-Agent cabeçalho

O Braze inclui um cabeçalho User-Agent em todas as solicitações de Connected Content e webhook que é semelhante ao seguinte:

1
Braze Sender 75e404755ae1270441f07eb238f0faf25e44dfdc

Solução de problemas

Use Webhook.site para solucionar problemas em suas chamadas de conteúdo conectado.

1. Altere a URL em sua chamada de Connected Content com a URL exclusiva gerada no site.
2. Faça uma prévia e teste sua campanha ou etapa do canva para ver as solicitações que chegam a este site.

Usando essa ferramenta, você pode diagnosticar problemas com os cabeçalhos de solicitação, o corpo da solicitação e outras informações que estão sendo enviadas na chamada.

Perguntas frequentes

Por que há mais chamadas de Connected Content do que usuários ou envios?

O Braze pode fazer a mesma chamada à Connected Content API mais de uma vez por destinatário porque talvez seja necessário fazer uma chamada à Connected Content API para renderizar uma carga útil de mensagem. As cargas úteis de mensagens podem ser processadas várias vezes por destinatário para validação, lógica de nova tentativa ou outros fins internos.

Espera-se que uma chamada à Connected Content API possa ser feita mais de uma vez por destinatário, mesmo que a lógica de repetição não seja usada na chamada. Recomendamos definir o limite de frequência de qualquer mensagem que contenha Conteúdo Conectado ou configurar seus servidores para que sejam mais capazes de lidar com o volume esperado.

Como o limite de frequência funciona com o Connected Content?

O Connected Content não tem seu próprio limite de frequência. Em vez disso, o limite de frequência é baseado na taxa de envio de mensagens. Recomendamos definir o limite de frequência de envio de mensagens abaixo do limite de frequência de Connected Content pretendido se houver mais chamadas de Connected Content do que mensagens enviadas.

O que é comportamento de cache?

Por padrão, as solicitações POST não são armazenadas em cache. No entanto, você pode adicionar o parâmetro :cache_max_age para forçar a chamada POST para o cache.

O armazenamento em cache pode ajudar a reduzir as chamadas duplicadas do Connected Content. No entanto, não é garantido que isso sempre resulte em uma única chamada de Connected Content por usuário.

Qual é o comportamento padrão do Connected Content HTTP?

Por padrão, o conteúdo conectado definirá um Content-Type cabeçalho em uma solicitação HTTP GET que ele faz para application/json com Accept: */*. Se precisar de outro tipo de conteúdo, especifique-o explicitamente adicionando :content_type your/content-type à tag. A Braze definirá então tanto o cabeçalho Content-Type quanto o cabeçalho Accept para o tipo que você especificar.

1
{% connected_content http://numbersapi.com/random/trivia :content_type application/json %}

Por padrão, o conteúdo conectado faz uma solicitação HTTP GET para a URL especificada. Para fazer uma solicitação POST, especifique :method post.

Você pode opcionalmente fornecer um corpo POST especificando :body seguido por uma consulta string do formato key1=value1&key2=value2&... ou uma referência aos valores capturados. O tipo de conteúdo padrão é application/x-www-form-urlencoded. Se você especificar :content_type application/json e fornecer um corpo codificado em formulário, como key1=value1&key2=value2, a Braze codificará automaticamente o corpo em JSON antes de enviar.

O Connected Content também não armazena em cache as chamadas POST por padrão. Você pode atualizar esse comportamento adicionando :cache_max_age à chamada POST do Connected Content.

• default content-type
• application/json content-type

1
{% connected_content https://example.com/api/endpoint :method post :body key1=value1&key2=value2 %}

1
{% connected_content https://example.com/api/endpoint :method post :body key1=value1&key2=value2 :content_type application/json %}