API OneLink

Premium

Para:

Última atualização: 14 de Agosto de 2023 12:32

Visão geral: a API do OneLink ajuda você a engajar os usuários finais e utilizar suas mídias próprias, gerando links personalizados em campanhas em grande escala, via SMS e muito mais. Requer anunciante e desenvolvedor para implementar.

API OneLink

A API do OneLink é usada para:

Criar, obter, atualizar e excluir URLs curtas do OneLink com parâmetros personalizados automaticamente.
Os parâmetros podem ser:
- Parâmetros relacionados à atribuição, usados para mensurar e monitorar esforços de marketing, como fonte de mídia, campanha e recurso. Observação: o parâmetro fonte de mídia (pid) é obrigatório.
- Parâmetros de personalização, que permitem configurar uma experiência de usuário personalizada ao abrir o aplicativo a partir de um link relevante. Esses parâmetros permitem que você envie usuários para conteúdo personalizado no aplicativo, por exemplo uma página de produto específica, código de cupom ou promoção.
Permitir o compartilhamento de conteúdo do site e do aplicativo diretamente para usuários mobile (aumentando assim o engajamento e as instalações mobile).
Gere instantaneamente um grande número de links de atribuição personalizados do OneLink.
Observação: para links de referência, consulte o artigo de atribuição de convites de usuários.

Exemplo

Feed Me, um serviço de entrega de supermercado, quer enviar um link personalizado via SMS para clientes existentes, incentivando-os a baixar o aplicativo Feed Me e comprar bananas. Com base no país do cliente, o Feed Me usa a API REST do OneLink para criar uma URL personalizada do OneLink que contém detalhes específicos para o país, a identidade do usuário e uma oferta especial para bananas na promoção.

A quantidade de consultas da API do OneLink que você pode fazer é limitada dependendo do tipo de conta. Você pode ver quantas consultas você fez e quantas ainda restaram no dashboard da API do OneLink.

Você pode entrar em contato com seu CSM para aumentar o limite de consultas da API.

Configuração

Para configurar a API do OneLink:

Crie um template do OneLink.
Registre o ID do OneLink.
Grave a chave da API do OneLink. Um usuário administrador precisa recuperar a chave API; os usuários da conta não têm acesso.
- No dashboard da AppsFlyer, acesse Experiências e Deep Linking> API do OneLink>Ver chave da API do OneLink
- Se a chave de API do OneLink não estiver lá para um usuário administrador, isso significa que você não tem o pacote necessário e precisa entrar em contato com seu CSM.
Forneça o ID do OneLink e a chave de API do OneLink ao desenvolvedor.
Diga ao desenvolvedor para seguir as instruções no hub de dev.

Painel

O dashboard da API do OneLink exibe:

Seu uso diário, mensal e trimestral da API.
A chave da API do OneLink.

Para visualizar o dashboard da API do OneLink:

Na AppsFlyer, acesse Experiências e Deep Linking > API do OneLink.

Características e limitações

Característica	Observações
Limite de cota de API	O limite para usar a API do OneLink para criar, editar ou excluir links do OneLink é de 7,5 milhões por mês (fuso horário UTC), por conta. Todas as requisições feitas após ultrapassar esta cota não são atendidas, e os links não são criados; a chamada de API recebe o código de status de erro 429 com a mensagem "Cota mensal excedida". As informações sobre quanto da cota de taxa é usada/permanece são exibidas no painel da API do OneLink.
Limite de taxa	O limite de taxa da API por conta é de 500 solicitações por segundo (30.000 por minuto). Todas as requisições que são feitas acima de 500 requisições por segundo (30000 por minuto) não são atendidas, e os links não são criados; a chamada de API recebe o código de status de erro 429 com a mensagem "Limite de taxa excedido".
Visibilidade do link	Os links criados por meio da API não aparecem na lista de links personalizados do OneLink no dashboard da AppsFlyer. Prática recomendada: salve links criados por API em uma tabela local, para que você possa acessar os links para qualquer finalidade futura.
TTL	O tempo padrão de vida (TTL) para os URLs curtos OneLink criados via API OneLink é de 31 dias. Ele é estendido por 31 dias cada vez que o link é clicado. Clicar no link depois que o TTL expirar gera o mesmo comportamento definido na configuração de base do OneLink, mas a atribuição não funcionará. Pode levar até 48 horas para que um URL curto do OneLink seja excluído após a expiração do TTL. O TTL máximo é de 31 dias. Qualquer valor TTL maior que 31 é substituído com o TTL padrão de 31. Você pode alterar o TTL padrão adicionando o parâmetro `ttl={value}` e especificando quantos dias, horas ou minutos. Por exemplo `ttl=7d`, `ttl=12h`, ou `ttl=10m`. Você pode enviar uma solicitação de atualização para especificar o TTL. Qualquer solicitação de atualização redefine o TTL (para links existentes) para o valor especificado no corpo da solicitação. Isso significa que o TTL é substituído. Por exemplo, se você fizer uma chamada de atualização com TTL de 2d (2 dias) para um link que atualmente tem TTL de 29d, ele mudará para TTL=2d (não 31d). Uma chamada de atualização pode potencialmente prolongar a vida útil do link de atribuição. Por exemplo, se você fizer uma chamada de atualização com TTL de 31d para um link que atualmente tem TTL de 20d mas 5 dias se passaram, o TTL será de 31d a partir do momento da atualização. Se você não quiser que os TTLs do link se estendam automaticamente, adicione o parâmetro `renew_ttl=false` a seus links. O valor para este parâmetro é booleano, ou seja, verdadeiro (padrão) ou falso. O parâmetro `renew_ttl` não é exibido no URL atual.
Caracteres especiais	Os seguintes caracteres devem ser codificados se forem usados para links criados pela API: ;, , !, @, #, ?, $, ^, :, &, ~, `, =, +, ', >, <, /. Se você não codificar esses caracteres, eles serão substituídos por um espaço em branco e o link e sua funcionalidade podem quebrar.
Payload	A string de consulta do payload não pode exceder 2.048 caracteres.
ID do URL	O ID do URL (ou ID do link curto) pode ser editado para destacar a oferta da sua campanha. Por exemplo: https://meuapp.onelink.com/abc123/maçãs. O ID do URL não deve ultrapassar 50 caracteres e pode ser uma combinação de letras e números. Por padrão, são 8 caracteres. Observação: Você só pode editar o ID do URL se o ID atual ainda não estiver em uso. Se o ID do URL já estiver em uso, a criação do link falhará e retornará uma resposta de erro (400). Você e seu desenvolvedor precisam decidir e configurar o que acontece nesse evento. A chamada com falha ainda conta para sua cota mensal de API.