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

Table of contents
📦 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
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
import { ReactNode, useEffect } from 'react'
import {
EventDispatcherProvider as OlaIsaacEventDispatcherProvider,
useEventDispatcher,
} from '@olaisaac/event-dispatcher-sdk'
type ComponentProps = { children: ReactNode }
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: {
$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
import { ReactNode, useEffect } from 'react'
import {
EventDispatcherProvider as OlaIsaacEventDispatcherProvider,
useEventDispatcher,
} from '@olaisaac/event-dispatcher-sdk'
type ComponentProps = { children: ReactNode }
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: {
$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:
export enum EventDispatcherEvents {
NOME_DO_EVENTO = 'NOME_DO_EVENTO',
}
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: {
$example: 'example-custom-property',
},
})
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