Ingestão de Dados - Integração de PAM ao Xtremepush

O Xtremepush suporta uma variedade de métodos de ingestão para garantir compatibilidade com sua stack tecnológica existente. Se nenhuma das opções de integração abaixo for adequada, consulte seu contato XP para uma discussão mais aprofundada sobre o que é possível.

1. API REST

A API externa em tempo real é ideal para importar novos clientes, atualizar atributos e registrar eventos de acesso. Isso significa que você terá um conector Xtremepush no seu PAM, que será ativado com URLs e credenciais recuperadas do projeto relacionado no ambiente Xtremepush no momento da configuração. Ele suporta altos volumes e processamento em lote via o endpoint de hit de eventos em lote. Os principais pontos finais para revisão são a importação de perfil (que também pode ser usada para atualizar perfis existentes) e event hit. Eventos também podem ser enviados em lote usando o endpoint de batch event hit.

Detalhes sobre quais APIs são normalmente usadas abaixo.

Inicialização do Esquema de Atributos

Além do seu próprio esquema de atributos configurável, o Xtremepush possui um conjunto de atributos principais do sistema para os quais você precisará mapear certos atributos. Esses casos se referem predominantemente ao ID principal do jogador, atributos de contato do canal como e-mail e número de celular, e permissão de marketing de canal. Atributos reservados do sistema podem ser encontrados aqui: atributos do sistema

Antes de configurar seu esquema de atributos, você deve revisar esses atributos reservados e quaisquer atributos equivalentes devem ser mapeados para esses atributos padrão. Atributos personalizados além desses podem ser configurados para atender aos requisitos.

Temos uma API que pode ser usada para inicializar o perfil personalizado desejado, detalhes do esquema do atributo podem ser encontrados aqui: tag-create

Essas APIs são muito diretas, baseadas em JSON, por exemplo, para inicializar um atributo de perfil que armazena dias desde a última aposta feita em que você postaria algo como:

{
    "apptoken": "YOUR_APPTOKEN",
    "title": "days_since_last_bet_placed",
    "attribute_profile": 1,
    "type": 1
}

Existe uma versão em lote dessa API para inicializar todos os atributos em uma única chamada, se necessário:

tag-batch-criar

Você pode usar essas APIs para tornar configurável quais atributos serão configurados para exportação a partir do PAM.

Sincronização de Atributos em Massa

Se você quiser fazer uma sincronização inicial de atributos ou resincronizações em massa ocasionais, existe uma API de importação de atributos em lote. Detalhes podem ser encontrados aqui: importação de perfil de usuário
Como mencionado na seção anterior, os nomes padrão devem ser direcionados para atributos do sistema como ID de usuário, e-mail e permissões de canal. Os lotes devem ser mantidos em um máximo de 10.000 registros em uma única solicitação.

Eventos em Tempo Real

Para transações/eventos em andamento e quaisquer alterações relacionadas nos atributos, o endpoint da API de eventos pode ser usado para enviar esses eventos um de cada vez conforme acontecem. Detalhes podem ser encontrados aqui: evento-impacto-evento

Essas APIs permitem que eventos como apostas sejam repassados, como mostrado no exemplo simples abaixo. Informações relacionadas, como o conteúdo do boleto de apostas, podem ser passadas abaixo do valor parâmetro. JSON aninhado pode ser usado aqui conforme necessário para dados mais complexos, como conteúdos de betslip. Se algum atributo de usuário precisar ser atualizado, esses valores podem ser passados sob o parâmetro user_attribute.

{
    "apptoken": "YOUR_APPTOKEN",
    "user_id": 12345,
    "user_attributes": {
      "balance": 76.09,
         },
    "event": "bet_placed",
    "value": {
     "amount": 50,
"product": "Sport",
"provider": "57",
"balance_after": 76.09
    },
    "timestamp": "2023-01-01 12:00:00"
  }

Eventos não precisam ser uma transação, eles podem ser mais sobre inicialização do usuário ou atualização de atributos-chave conforme mudam. Por exemplo, você pode ter um evento de registro de jogador que define vários valores de atributos de usuário pela primeira vez. Da mesma forma, eventos de exclusão podem ser usados para definir atributos de perfil chave, o que fará com que os usuários sejam imediatamente filtrados por exclusões globais; por exemplo, você pode ter um evento de mudança de status da conta que define o status da conta para fechado ou congelado.

2 Ingestão de Stream (Kafka & Streams em Tempo Real)

Kafka é o método recomendado para a ingestão de eventos em tempo real e de alto volume. É particularmente eficaz em ambientes de iGaming, onde apostas, acordos e saldos precisam ser processados com latência inferior a um segundo entre milhões de jogadores. Os consumidores podem ser escalados horizontalmente para garantir desempenho em menos de um segundo.

2.1 Arquitetura Kafka e Conceitos-Chave

Antes de iniciar sua integração, é importante entender como o Xtremepush interage com sua infraestrutura Kafka.

• Tópicos Os dados são organizados por tópicos. Cada projeto tem dois tópicos correspondentes: events e users. Credenciais únicas são fornecidas por projeto.

• Partições e Escalonamento Os tópicos podem ser separados em partições, permitindo que o Xtremepush escale os consumidores horizontalmente para lidar com maior rendimento. Mensagens com a mesma chave são roteadas para a mesma partição, garantindo que a ordem seja mantida por usuário.

• Compensações Cada consumidor mantém seu próprio registro de progresso (um compenso). Se uma conexão for interrompida, o Xtremepush retoma a partir do último deslocamento reconhecido para garantir que não haja perda de dados.

2.2 Abordagens de Integração

Existem duas rotas principais para estabelecer uma conexão Kafka. A rota escolhida determina o nível de configuração exigido da sua equipe técnica.

1. Push do cliente para Xtremepush (Padrão)

Essa é a rota mais eficiente e requer configuração apenas do lado do Xtremepush. Sua infraestrutura produz (envia) dados diretamente para os tópicos hospedados em nossos corretores no formato exigido.

Cada projeto é fornecido com dois tópicos (events e users) e um nome de usuário e senha únicos, fornecidos pelo suporte Xtremepush. Note que os atributos do perfil também podem ser definidos via um payload de evento usando o user_attributes objeto, da mesma forma que a API Xtremepush.

Autenticação

As conexões são estabelecidas usando SCRAM-SHA-512. As credenciais são únicas por projeto e fornecidas pelo suporte do Xtremepush.

O que precisamos de você

Para completar a configuração, exigimos o seguinte da sua equipe técnica:

• Os endereços IP de saída de onde sua infraestrutura enviará eventos.

• Confirmação de que você consegue se conectar via autenticação SCRAM-SHA-512.

• Volumes esperados de eventos — isso determina como escalamos os trabalhadores internos. Por favor, forneça estimativas tanto para ambientes de teste quanto de produção.

• Detalhes de qualquer necessidade de carregamento em massa — enviar grandes volumes de mensagens em um curto período pode causar atrasos no processamento. Se o carregamento em massa faz parte do seu caso, precisamos discutir isso desde o início. Veja a nota na seção de Tópicos de Usuários para mais detalhes.

• Quando você opera múltiplos projetos (por exemplo, diferentes marcas ou regiões), confirmação de que você pode produzir os dados de cada projeto para um conjunto separado de tópicos do nosso lado.

2.3 Formatos de Tópicos e Requisitos de Carga Útil

Todas as cargas úteis devem ser JSON válidas. Cada projeto tem dois temas, cada um com um propósito distinto.

Tema dos Eventos

Use este tópico para registrar eventos e ações que um usuário realiza (por exemplo, apostas, depósitos, logins).

• Nome do Tópico: Definido como parte da configuração

• Chave da Mensagem: Não é obrigatório, mas pode ser definido para um UUID único de evento. O Xtremepush irá deduplicar eventos dentro de uma janela de tempo configurável com base nessa chave. Para permitir a deduplicação do seu projeto, entre em contato com o suporte do Xtremepush.

• Cabeçalhos das Mensagens: Nenhum

• Corpo da Mensagem: Item codificado em JSON

Esquema

{
  "event": "some_event",
  "user_id": "some_user",
  "user_attributes": {
    "any_attr": "any_value"
  },
  "value": {
    "any_key": "any_value"
  },
  "timestamp": "2025-01-01 12:00:00"
}

Exemplo

{
  "event": "bet",
  "user_id": "3e685367-07d5-4d48-93ae-f007ac336605",
  "customer_id": 12345,
  "user_attributes": {
    "customer_tier": "VIP"
  },
  "value": {
    "bet_id": "3e685367-07d5-4d48-93ae-f007ac336605",
    "odds": 12.2,
    "stake": 100.0
  },
  "timestamp": "2024-09-01 12:00:00.123"
}

Tema dos Usuários

Use este tópico para criar novos usuários ou atualizar perfis de usuários existentes.

Nota sobre sequenciamento: Mensagens de perfil são processadas sequencialmente e importações grandes podem levar um tempo significativo para serem concluídas. Se eventos forem enviados sobre o events tema para usuários cujos perfis ainda não foram processados, esses eventos serão cancelados. Certifique-se de que a importação do seu perfil esteja completa antes de enviar eventos para esses usuários e evite carregar grandes volumes de mensagens de perfil em pouco tempo, sempre que possível.

• Nome do Tópico: Definido como parte da configuração

• Chave da Mensagem: Recomendado. Deve ser o identificador de usuário (por exemplo, user_id). Usado para manter a ordem dentro do fluxo Kafka — todas as mensagens com a mesma chave são roteadas para a mesma partição, garantindo que as atualizações de perfil sejam aplicadas na sequência correta.

• Cabeçalhos das Mensagens: Nenhum

• Corpo da Mensagem: Item codificado em JSON

Esquema

{
  "user_id": "some_user",
  "user_attributes": {
    "any_attr": "any_value"
  },
  "timestamp": "2025-01-01 12:00:00"
}

Exemplo

{
  "user_id": "3e685367-07d5-4d48-93ae-f007ac336605",
  "customer_id": 12345,
  "user_attributes": {
    "customer_tier": "VIP",
    "email": "john@doe.com"
  },
  "timestamp": "2024-09-01 12:00:00.123"
}

2.4 Domínios de Alto Volume (Estratégia de Agregação)

Quando o volume bruto de eventos é extremamente alto, como jogos em nível de spin ou deltas de carteiras rápidas, recomendamos agregação a montante antes que o cliente publique para o Kafka. Isso mantém o fluxo previsível, preservando o valor do negócio e gerenciando custos relacionados ao excedente do evento.

• Agregados baseados em sessões: Esses devem ser limitados pelo tempo (por exemplo, ≤10 min) ou contagem (por exemplo, ≤N giros). Devem incluir totais para apostas, vitórias, net, contagens, código do jogo, canal e carimbos de tempo para início e fim.

• Agregados de janelas rolantes: Normalmente, são resumos de 2 a 5 minutos agrupados por usuário ou produto.

3 Segmento

Xtremepush é um destino listado no Segment, permitindo configurações prontas para perfis e eventos. Isso é incrivelmente fácil de configurar tanto no Segmento, onde o Xtremepush é um destino listado, quanto na própria plataforma Xtremepush. A documentação sobre isso pode ser encontrada aqui.

4 SFTP

Pontos de dados com movimento mais lento ou arquivos de dados já compartilhados com outras plataformas podem ser enviados para um SFTP que o Xtremepush pode fornecer, ou podem ser captados de um SFTP pertencente ao cliente. Em ambos os casos, isso pode ser configurado diretamente pelo cliente dentro da plataforma. A documentação sobre isso pode ser encontrada aqui.

5 SDK

O aplicativo e os SDKs web do Xtremepush podem capturar perfis, atualizar atributos de perfil e coletar eventos em tempo real. Um pré-requisito fundamental para isso é definir o ID do usuário via o método SDK descrito mais adiante no documento. Isso ajudará a garantir que o grafo de identidade do Xtremepush associe corretamente os dispositivos e quaisquer dados coletados por eles com perfis que podem ser coletados ou atualizados por outras fontes. Tags usadas para acompanhar eventos e atualizar atributos de perfil podem ser encontradas na documentação vinculada às seções de integração iOS, Android e Web mais adiante neste documento.