Segment

Introdução

A integração com o Segment envia eventos do Dodo Payments para a HTTP Tracking API do Segment como chamadas Track e Identify. Em seguida, o Segment encaminha dados de pagamentos, assinaturas e clientes para as ferramentas de análise, marketing e data warehouse conectadas ao seu workspace, a partir de um catálogo com mais de 300 destinos.

Essa integração requer a Write Key de uma fonte HTTP API no seu workspace do Segment. Você também precisa ter acesso a Developer → Webhooks no dashboard do Dodo Payments.

Começando

Open the Webhook Section

No dashboard do Dodo Payments, acesse Developer → Webhooks e clique em Add endpoint.

Janela de diálogo Add endpoint com Segment selecionado no menu suspenso Integration e as etapas How to connect Segment

Select Segment

Em Integration, selecione Segment. O dashboard preenche a Endpoint URL e o código de transformação para o Segment.

Enter Write Key

No Segment, acesse Connections → Sources e abra ou crie uma fonte HTTP API. Copie a Write Key das configurações da fonte e cole-a em API key.

Select Events

Em Subscribed events, selecione apenas os eventos tratados pela sua transformação. Os exemplos nesta página usam payment.succeeded, subscription.active e subscription.cancelled.

Configure Transformation

Em Transformation code, edite o handler para formatar eventos para a Track ou Identify API do Segment. Comece pelos exemplos.

Test & Create

Em Test this code, selecione um tipo de evento e clique em Simulate para visualizar a chamada ao Segment. Em seguida, clique em Create endpoint.

Switch to Basic Authentication

O Dodo Payments envia o valor de API key como um bearer token, mas a HTTP API do Segment aceita uma Write Key por meio de autenticação Basic ou de um campo writeKey no body. Logo depois de criar o endpoint, abra a aba Advanced. Em Custom headers, insira um novo valor na linha Authorization oculta: Basic, um espaço e a codificação Base64 da sua Write Key com dois-pontos anexados. Em seguida, clique em Save. Por exemplo, echo -n 'YOUR_WRITE_KEY:' | base64 imprime o valor codificado.

Done

Os eventos inscritos agora chegam ao Segment, que os encaminha para os destinos conectados.

Exemplos de código de transformação

Cada handler define webhook.url como um endpoint da API do Segment e substitui webhook.payload pela chamada. Os valores do Dodo Payments estão na menor unidade da moeda, portanto os exemplos dividem os valores por 100. Para moedas sem casas decimais, como JPY e KRW, use o valor sem alterações.

Rastrear eventos de pagamento

Registre um evento Payment Completed quando um pagamento for bem-sucedido:

track_payments.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.segment.io/v1/track";
    webhook.payload = {
      userId: p.customer.customer_id,
      event: "Payment Completed",
      properties: {
        amount: (p.total_amount / 100).toFixed(2),
        currency: p.currency || "USD",
        payment_method: p.payment_method || "unknown",
        payment_id: p.payment_id,
        customer_email: p.customer.email,
        customer_name: p.customer.name
      },
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}

Rastrear o ciclo de vida da assinatura

Registre eventos Subscription Started e Subscription Cancelled:

track_subscriptions.js

function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.url = "https://api.segment.io/v1/track";
      webhook.payload = {
        userId: s.customer.customer_id,
        event: "Subscription Started",
        properties: {
          subscription_id: s.subscription_id,
          product_id: s.product_id,
          amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
          frequency: s.payment_frequency_interval,
          next_billing: s.next_billing_date,
          customer_email: s.customer.email
        },
        timestamp: webhook.payload.timestamp
      };
      break;
    case "subscription.cancelled":
      webhook.url = "https://api.segment.io/v1/track";
      webhook.payload = {
        userId: s.customer.customer_id,
        event: "Subscription Cancelled",
        properties: {
          subscription_id: s.subscription_id,
          product_id: s.product_id,
          cancelled_at: s.cancelled_at,
          cancel_at_next_billing: s.cancel_at_next_billing_date,
          customer_email: s.customer.email
        },
        timestamp: webhook.payload.timestamp
      };
      break;
  }
  return webhook;
}

Identificar propriedades do cliente

Atualize os traits do cliente após cada pagamento bem-sucedido. Cada chamada Identify define os traits com os valores enviados, portanto esses traits descrevem o pagamento mais recente:

identify_customer.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.segment.io/v1/identify";
    webhook.payload = {
      userId: p.customer.customer_id,
      traits: {
        email: p.customer.email,
        name: p.customer.name,
        last_payment_amount: (p.total_amount / 100).toFixed(2),
        payment_method: p.payment_method || "unknown",
        last_payment_date: webhook.payload.timestamp
      }
    };
  }
  return webhook;
}

Dicas

Use nomes de eventos consistentes em toda a integração, como o formato de objeto e ação do Segment em Payment Completed.
Inclua as propriedades necessárias para análise e segmentação.
Defina timestamp a partir de timestamp do evento, para que o Segment registre quando o evento ocorreu, e não quando foi recebido.
Use o customer_id do Dodo Payments como userId, para que cada chamada de um cliente seja associada ao mesmo usuário do Segment.

Solução de problemas

Events Not Appearing in Segment

Verifique se a Write Key pertence a uma fonte HTTP API e se o header Authorization usa autenticação Basic.
O Segment retorna 200 para a maioria das solicitações, inclusive as que não aceita, portanto uma entrega bem-sucedida nos logs do Dodo Payments não comprova que o evento chegou. Verifique o Debugger da fonte no Segment.
Verifique se os nomes dos eventos seguem as convenções de nomenclatura do Segment.
Verifique se cada chamada define userId. O Segment rejeita uma chamada que não tenha userId nem anonymousId.
Verifique os limites de taxa do Segment para a HTTP API. O Segment recomenda permanecer abaixo de 1.000 solicitações por segundo por workspace.
Se o seu workspace usa a região da UE do Segment, envie as chamadas para https://events.eu1.segmentapis.com/v1/track e https://events.eu1.segmentapis.com/v1/identify.

Transformation Errors

Verifique se o payload corresponde ao formato da API do Segment.
Verifique se todos os campos obrigatórios estão presentes. Track requer event, e Track e Identify exigem userId ou anonymousId.
Verifique se os nomes dos eventos são strings, não objetos.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Introdução

Começando

Exemplos de código de transformação

Rastrear eventos de pagamento

Rastrear o ciclo de vida da assinatura

Identificar propriedades do cliente

Dicas

Solução de problemas

​Introdução

​Começando

​Exemplos de código de transformação

​Rastrear eventos de pagamento

​Rastrear o ciclo de vida da assinatura

​Identificar propriedades do cliente

​Dicas

​Solução de problemas

Introdução

Começando

Exemplos de código de transformação

Rastrear eventos de pagamento

Rastrear o ciclo de vida da assinatura

Identificar propriedades do cliente

Dicas

Solução de problemas