Eventos do Widget

O widget de fidelidade se comunica com sua aplicação por meio da API do postMessage navegador. Isso permite que você gerencie eventos do ciclo de vida dos widgets, erros de autenticação e interações com usuários.

Todos os eventos do widget incluem source: "Scrimmage" no payload para identificar o remetente.

Ouça eventos widget

Adicione um ouvinte de evento de mensagem ao seu aplicativo:

window.addEventListener('message', (event) => {
  // Verify the event origin matches your loyalty widget domain
  // Replace WIDGET_ORIGIN with your actual widget URL from the environment table
  const WIDGET_ORIGIN = 'https://p<project_id>.p.loyalty.<environment>.xtremepush.com';
  
  if (event.origin !== WIDGET_ORIGIN) {
    return;
  }

  const { source, type, payload } = event.data;

  if (source !== 'Scrimmage') {
    return;
  }

  switch (type) {
    case 'ready':
      console.log('Widget loaded successfully');
      break;
    case 'error':
      console.error('Widget error:', payload);
      break;
    case 'redirect':
      handleRedirect(payload);
      break;
  }
});

Substitua <project_id> e <environment> insca WIDGET_ORIGIN pela URL real do seu widget. Veja Carregar o Widget para o formato correto da URL.

Eventos Outbound

O widget envia os seguintes eventos para sua aplicação.

Pronto

É disparado quando o widget for carregado com sucesso e o usuário puder interagir com o programa de fidelidade.

Carga útil:

{
  "source": "Scrimmage",
  "type": "ready",
  "payload": {}
}

Quando usar: Mostre um indicador de carregamento até que esse evento dispare, ou acompanhe a análise de carga de widgets.

Erro

Disparado quando a autenticação ou inicialização falha.

Carga útil:

{
  "source": "Scrimmage",
  "type": "error",
  "payload": {
    "type": "auth:init-failed",
    "message": "Initializing user failed",
    "data": {
      "status": 403
    }
  }
}

Tipos de erro:

Para todos os erros de autenticação, verifique a lógica de geração do token e a configuração da chave pública. Veja Gerenciar Autenticação do Usuário para os requisitos de tokens. Entre em contato com o suporte se os erros persistirem.

Quando usar: Exibir mensagens de erro para o usuário ou falhas de autenticação em log para depuração.

redirecionar

Demitido quando um usuário clica em um link profundo configurado em uma missão, conquista ou outro recurso de fidelidade.

Carga útil:

{
  "source": "Scrimmage",
  "type": "redirect",
  "payload": {
    "redirect": "some_deep_link",
    "parameters": {
      "target": "quest",
      "quest": {
        "status": "not-started",
        "progress": 0,
        "periodDeadline": null,
        "challenges": [
          { "completed": false, "progress": 0 }
        ],
        "user": { "id": "user_12345" },
        "quest": {
          "id": "20245278-f038-4053-b77a-63c74f5e80e8",
          "title": "Place 5 live bets",
          "onClickRedirect": "some_deep_link"
          // ...full quest configuration
        }
      },
      "userResources": {
        "tokens": 500,
        "levelConfig": { "level": 1, "name": "Level 1" },
        "nextLevelConfig": { "level": 2, "name": "Level 2" },
        "attributes": {
          "level.current": 1,
          "reward.primaryReward": 500,
          "quest.completionsTotal": 0
          // ...all user attributes and segment memberships
        }
      }
    }
  }
}

Campos de carga útil:

• redirecionamento: A string de deep link configurada no campo do onClickRedirect recurso de fidelidade. Clicar no link não aciona nenhuma navegação dentro do widget. O valor é passado para sua aplicação, que cuida da navegação.

• parameters.target: Identifica qual recurso acionou o redirecionamento, por exemplo, quest.

• parameters.quest: Snapshot do progresso do usuário na missão mais a configuração completa da missão. Presente quando target é quest.

• parameters.userResources: Snapshot dos recursos do usuário no momento do clique, incluindo configuração atual e de próximo nível, além de um attributes mapa contendo todos os atributos do sistema do usuário, atributos personalizados e membros de segmentos. Para uma lista completa de atributos do sistema, veja Gerenciar Atributos de Lealdade.

Quando usar: Navegue até a URL especificada no seu aplicativo ou use parameters para personalizar o destino com base no estado do usuário.

Eventos de entrada

Sua aplicação pode enviar os seguintes eventos para o widget.

auth:token

Envie um novo token de autenticação para atualizar uma sessão expirada sem recarregar o widget.

Como enviar:

const widgetIframe = document.getElementById('loyalty-widget-iframe');

// Replace with your actual widget URL from the environment table
widgetIframe.contentWindow.postMessage(
  {
    type: 'auth:token',
    payload: {
      token: 'eyJhbGc...' // New JWT token
    }
  },
  'https://p<project_id>.p.loyalty.<environment>.xtremepush.com'
);

Substitua <project_id> e <environment> por sua URL real do widget. Veja Carregar o Widget para o formato correto da URL.

Quando usar: Quando você receber um auth:token-expired evento de erro, gere um novo token no seu backend e envie-o para o widget usando esse evento. Isso evita interromper a sessão do usuário.