@olaisaac/event-dispatcher-sdk v0.2.42-stable
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
// 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
💡 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 |
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
6 months ago
6 months ago
6 months ago
6 months ago
10 months ago
6 months ago
6 months ago
7 months ago
10 months ago
10 months ago
10 months ago
6 months ago
7 months ago
10 months ago
6 months ago
6 months ago
7 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
11 months ago
12 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
11 months ago
12 months ago
11 months ago
12 months ago
11 months ago
12 months ago
1 year ago