@olaisaac/event-dispatcher-sdk

Event Dispatcher SDK

📅 SDK oficial para envio de eventos client-side para métricas de produto

• RFC do projeto
• RFC de captura de eventos

Table of contents

• Instalação
• Guia básico de uso
  • Crie um arquivo para configurar o contexto
  • Configure as propriedades globais dos eventos
  • Identifique o usuário que irá emitir os eventos
  • Emita eventos utilizando o SDK
• Playground
• Como contribuir
• Próximos passos

📦 Instalação

O Event Dispatcher é disponibilizado como um pacote NPM.

yarn add @olaisaac/event-dispatcher-sdk

⚡ Guia básico de uso

💡 É altamente recomendo que você comece lendo a RFC do projeto

Comece configurando o contexto React exposto pela lib:

Crie um arquivo para configurar o contexto

// src/contexts/EventDispatcher/index.tsx

import { ReactNode, useEffect } from 'react'
import { EventDispatcherProvider as OlaIsaacEventDispatcherProvider } from '@olaisaac/event-dispatcher-sdk'

type ComponentProps = { children: ReactNode }

export const EventDispatcherProvider = ({ children }: ComponentProps) => {
  return (
    <OlaIsaacEventDispatcherProvider
      options={{
        mixpanelDebugMode: '<MIXPANEL_DEBUG_MODE>',
        mixpanelProjectToken: '<MIXPANEL_PROJECT_TOKEN>',
        portalEventsHost: '<PORTAL_EVENTS_HOST>',
      }}
      unleashProxyUrl="YOUR_UNLEASH_PROXY_URL"
      unleashClientKey="YOUR_UNLEASH_CLIENT_KEY"
      // isMixpanelEnabled={true}
      // isPortalEventsEnabled={false}
    >
      {children}
    </OlaIsaacEventDispatcherProvider>
  )
}

Esse arquivo, por enquanto, retorna apenas o contexto que foi importado da lib. Ele será responsável por inicializar a ferramenta e, para isso, é necessário fornecer as variáveis ambientes necessárias através da propriedade options.

• mixpanelDebugMode: [Opcional] Indica se os logs do Mixpanel estão habilitados. O valor padrão é false (ver mais)
• mixpanelProjectToken: Token do projeto Mixpanel que será utilizado
• portalEventsHost: URL do Portal Events

O Event Dispatcher tem a capacidade de utilizar múltiplos providers simultaneamente, a ativação dessas ferramentas é determinada por feature-flags gerenciadas pelo Unleash (ver mais).

Providers: Ferramentas para emissão de eventos. Ex: Mixpanel e Portal Events

Para que a lib consiga acessar as feature-flags é necessário fornecer as propriedades unleashProxyUrl e unleashClientKey.

É possível sobrescrever os valores definidos pelas feature-flags através das propriedades isMixpanelEnabled e isPortalEventsEnabled:

• isMixpanelEnabled: Determina se o provider do Mixpanel deve ser utilizado
• isPortalEventsEnabled: Determina se o provider do Portal Events deve ser utilizado.

Configure as propriedades globais dos eventos

// src/contexts/EventDispatcher/index.tsx

import { ReactNode, useEffect } from 'react'
import {
  EventDispatcherProvider as OlaIsaacEventDispatcherProvider,
  useEventDispatcher, // Importe o hook para consumir o SDK
} from '@olaisaac/event-dispatcher-sdk'

type ComponentProps = { children: ReactNode }

// Crie um componente para definir algumas configurações iniciais
const EntryComponent = ({ children }: EntryComponentProps) => {
  const { eventDispatcherClient, isInitialized } = useEventDispatcher()

  useEffect(() => {
    const initEventDispatcher = async () => {
      if (isInitialized) {
        const response = await eventDispatcherClient.setGlobalProperties({
          application: '<NOME_DA_APLICAÇÃO>',
          environment: '<AMBIENTE_DA_APLICAÇÃO>',
          realm: '<REALM>',
          customProperties: {
            // Eventuais propriedades customizadas
            $example: 'example-global-property',
          },
        })

        console.log({ response })
      }
    }

    initEventDispatcher().catch(() => {})
  }, [eventDispatcherClient, isInitialized])

  return <>{children}</>
}

export const EventDispatcherProvider = ({ children }: ComponentProps) => {
  return (
    <OlaIsaacEventDispatcherProvider
      options={{
        mixpanelDebugMode: '<MIXPANEL_DEBUG_MODE>',
        mixpanelProjectToken: '<MIXPANEL_PROJECT_TOKEN>',
        portalEventsHost: '<PORTAL_EVENTS_HOST>',
      }}
      unleashProxyUrl="YOUR_UNLEASH_PROXY_URL"
      unleashClientKey="YOUR_UNLEASH_CLIENT_KEY"
      // isMixpanelEnabled={true}
      // isPortalEventsEnabled={false}
    >
      <EntryComponent>{children}</EntryComponent>
    </OlaIsaacEventDispatcherProvider>
  )
}

No código acima foi adicionado um componente que realiza uma chamada utilizando o hook do Event Dispatcher. Essa chamada serve para definir as propriedades globais dos eventos. Essa função suporta os seguintes parâmetros:

• application: Representa o nome da aplicação
• environment: Representa o ambiente em que a aplicação está sendo executada (production, development ou staging)
• realm: Representa o realm que a aplicação está utilizando.
• customProperties: [Opcional] Permite a adição de propriedades customizadas

Identifique o usuário que irá emitir os eventos

// src/contexts/EventDispatcher/index.tsx

import { ReactNode, useEffect } from 'react'
import {
  EventDispatcherProvider as OlaIsaacEventDispatcherProvider,
  useEventDispatcher, // Importe o hook para consumir o SDK
} from '@olaisaac/event-dispatcher-sdk'

type ComponentProps = { children: ReactNode }

// Crie um componente para definir algumas configurações iniciais
const EntryComponent = ({ children }: EntryComponentProps) => {
  const { eventDispatcherClient, isInitialized } = useEventDispatcher()

  useEffect(() => {
    const initEventDispatcher = async () => {
      if (isInitialized) {
        const identifyUser = eventDispatcherClient.identifyUser({
          userId: 'example_id',
        })

        const setGlobalProperties = eventDispatcherClient.setGlobalProperties({
          application: '<NOME_DA_APLICAÇÃO>',
          environment: '<AMBIENTE_DA_APLICAÇÃO>',
          realm: '<REALM>',
          customProperties: {
            // Eventuais propriedades customizadas
            $example: 'example-global-property',
          },
        })

        const responses = await Promise.all([identifyUser, setGlobalProperties])

        console.log({ responses })
      }
    }

    initEventDispatcher().catch(() => {})
  }, [eventDispatcherClient, isInitialized])

  return <>{children}</>
}

export const EventDispatcherProvider = ({ children }: ComponentProps) => {
  return (
    <OlaIsaacEventDispatcherProvider
      options={{
        mixpanelDebugMode: '<MIXPANEL_DEBUG_MODE>',
        mixpanelProjectToken: '<MIXPANEL_PROJECT_TOKEN>',
        portalEventsHost: '<PORTAL_EVENTS_HOST>',
      }}
      unleashProxyUrl="YOUR_UNLEASH_PROXY_URL"
      unleashClientKey="YOUR_UNLEASH_CLIENT_KEY"
      // isMixpanelEnabled={true}
      // isPortalEventsEnabled={false}
    >
      <EntryComponent>{children}</EntryComponent>
    </OlaIsaacEventDispatcherProvider>
  )
}

Agora o componente EntryComponent realiza mais uma chamada utilizando o SDK. Essa chamada identifica um usuário por um ID, esse ID deve ser o mesmo ID do usuário do IAM para que seja possível identificar o usuário caso necessário.

Feita a identificação do usuário, todos os eventos emitidos a partir desse momento serão associados a ele.

Emita eventos utilizando o SDK

Para emitir os eventos basta chamar a função sendEvent disponibilizado pelo client. Mas antes você deve criar enums para definir os nomes e escopos dos eventos:

// src/shared/models/enums/EventDispatcherEvents.enum.ts

export enum EventDispatcherEvents {
  NOME_DO_EVENTO = 'NOME_DO_EVENTO',
}

// src/shared/models/enums/EventDispatcherEventScopes.enum.ts

export enum EventDispatcherEventScopes {
  ESCOPO_DO_EVENTO = 'ESCOPO_DO_EVENTO',
}

Tendo os enums criados, basta realizar a chamada da função como no exemplo abaixo:

// [...]

const { isInitialized, eventDispatcherClient } = useEventDispatcher()

// [...]

isInitialized &&
  eventDispatcherClient.sendEvent({
    scope: EventDispatcherEventScopes.ENROLLMENT_REPORT,
    name: EventDispatcherEvents.ENROLLMENT_PAYOUT_DATE_CHANGE,
    action: 'click',
    entity: 'event-entity',
    customProperties: {
      // Eventuais propriedades customizadas
      $example: 'example-custom-property',
    },
    // portalEventsProperties: {
    //   $category: '',
    //   $group: '',
    //   $type: '',
    //   $userId: '',
    // },
  })

Para enviar um evento é necessário fornecer as seguintes informações:

• name: Define o nome do evento
• scope: Define o escopo da aplicação que contém o evento
• entity: [Opcional] Define a entidade que sofre interação através do evento disparado.
• customProperties: [Opcional] Objeto que recebe propriedades customizadas para um evento.
• portalEventsProperties: [Opcional] Propriedade temporária para dar suporte ao provider do Portal Events. Esse objeto necessita das seguintes propriedades: $userId, $group, $category, $type.

🛝 Playground

Helpers - remove_properties_from_mixpanel_profiles

Trata-se de um script auxiliar para remover de forma rápida propriedades dos perfis do Mixpanel.

🔧 Como contribuir

Guia de contribuição

💡 Próximos passos

Ticket	Descrição
PAYOUT-1954	Desenvolvimento de testes unitários
BRPS-439	Automatizar changelog
BRPS-411	Descontinuar o Portal Events
BRPS-412	Adicionar status de erros
BRPS-414	Construir uma aplicação React para testar o SDK
BRPS-413	Ferramenta de log