Pular para o conteúdo principal

Módulo de CRM

O Módulo de CRM fornece funcionalidade para gerenciar notificações push da web, notificações in-app e Rich Inbox no Gamanza Engage Web Client SDK. Ele permite que os desenvolvedores registrem jogadores para notificações push da web, gerenciem solicitações de permissão de notificação, manipulem notificações push in-app do OneSignal e gerenciem mensagens de caixa de entrada (listar, contar, alternar leitura/favorito, excluir).

Acessando o Módulo

O CrmModule é inicializado internamente pelo SDK e não deve ser instanciado diretamente. Ele é acessível através da instância principal do SDK.

// Exemplo de acesso ao CrmModule através do SDK
const { Crm } = GamanzaEngageWebClientSDK.getInstance();

Métodos

playerRegisterWebPushSubscription

Registra o jogador autenticado atual para Notificações Push da Web alimentadas pelo Gamanza Engage CRM. Esta função registra o service worker, valida se o agente de usuário do jogador suporta push e também valida se as permissões para Notificações foram concedidas ou negadas.

Assinatura:

playerRegisterWebPushSubscription(): Promise<{
status: WebPushSubscriptionRequestStatus;
}>

Retorna:

TipoDescrição
Promise<{ status: WebPushSubscriptionRequestStatus }>Uma promessa que é resolvida em um objeto contendo o status da solicitação de assinatura de push da web.

Exemplo:

// Registrar-se para notificações push da web
const handleRequestPermissionsClick = async (evt) => {
evt.preventDefault();
// Esta chamada exibe a solicitação de permissões de notificação do agente de usuário nativo
const result = await Crm.playerRegisterWebPushSubscription();
if (result.status === WebPushSubscriptionRequestStatus.SUCCESS) {
alert('Parabéns, você está inscrito para receber Notificações Push');
} else if (result.status === WebPushSubscriptionRequestStatus.WEB_PUSH_NOT_SUPPORTED) {
alert('Notificações Push da Web não são suportadas neste navegador');
} else if (result.status === WebPushSubscriptionRequestStatus.WEB_PUSH_PERMISSION_DENIED) {
alert('A permissão para receber notificações foi negada');
}
};

// Anexar a um evento de clique de botão
document.getElementById('notification-permission-btn').addEventListener('click', handleRequestPermissionsClick);

Observações:

  • Para o Safari, a solicitação precisa estar atrás de uma interação do usuário. Quando o usuário concluir o gesto, chame o método de assinatura push imediatamente do código do manipulador de eventos do gesto.
  • Para requisitos, verifique a documentação de Configuração de Push da Web.

shouldShowNotificationRequestPermissionsBanner

Função de helper para permitir que você decida quando mostrar o banner de solicitação de permissões para Notificações Push da Web. Isso é particularmente útil para o Safari, onde o método de assinatura push deve ser chamado imediatamente do código do manipulador de eventos do gesto do usuário.

Assinatura:

shouldShowNotificationRequestPermissionsBanner(days: number = 30, override: boolean = true): Promise<boolean>

Parâmetros:

NomeTipoPadrãoDescrição
daysTipo number30Número de dias para esperar antes de mostrar o banner novamente. O sistema armazena este valor no armazenamento persistente.
overrideTipo booleanverdadeiroDefine se você deseja gravar no armazenamento de persistência na próxima vez em que a função deve retornar true para o jogador atual.

Retorna:

TipoDescrição
Promise<boolean>Uma promessa que é resolvida em um booleano indicando se o banner de solicitação de permissões de notificação deve ser exibido.

Exemplo:

Verificação automática e substituição da próxima verificação:

// Verifique se devemos exibir o banner de permissões de notificação
if (await Crm.shouldShowNotificationRequestPermissionsBanner(5)) {
// Exibir o banner na interface do usuário
showNotificationBanner();
}

Substituição do controle na persistência:

// Verifique se devemos exibir o banner sem atualizar a persistência
if (await Crm.shouldShowNotificationRequestPermissionsBanner(5, false)) {
// Exibir o banner na interface do usuário
showNotificationBanner();
}

// Manipulador para o jogador fechar o banner
const onCloseBannerClick = async (evt) => {
evt.preventDefault();
hideNotificationBanner();

// Atualize quando o banner deve ser exibido da próxima vez para 5 dias
await Crm.shouldShowNotificationRequestPermissionsBanner(5, true);
};

playerOneSignalInAppPushNotificationsSubscription

Registra o jogador autenticado atual para notificações push in-app do OneSignal. Este método permite registrar um jogador para receber notificações push através do OneSignal dentro do aplicativo.

Assinatura:

playerOneSignalInAppPushNotificationsSubscription(subs: OneSignalInAppNotificationSubscription): Promise<SimpleResponse<null>>

Parâmetros:

NomeTipoDescrição
subsOneSignalInAppNotificationSubscriptionOs detalhes da assinatura do OneSignal.

Retorna:

TipoDescrição
Promise<SimpleResponse<null>>Uma promessa que é resolvida em um objeto SimpleResponse indicando o sucesso ou falha do registro.

Exemplo:

const subscription = {
appId: "your-onesignal-app-id",
subscriptionId: "subscription-id",
playerId: "player-id",
deviceType: "web",
oneSignalId: "onesignal-id"
};

const result = await Crm.playerOneSignalInAppPushNotificationsSubscription(subscription);
if (result.ok) {
console.log("Registrado com sucesso para notificações do OneSignal");
} else {
console.error("Falha ao se registrar para notificações do OneSignal:", result.error);
}

Rich Inbox

A API do Rich Inbox permite listar, contar e gerenciar mensagens da caixa de entrada (status de leitura/favorito, excluir). Todos os métodos usam o caminho base /api/rich-inbox/v1 e retornam SimpleResponse<T>.

richInboxDeleteMessages

Exclui mensagens por seus IDs.

Assinatura:

richInboxDeleteMessages(body: RichInboxIdsBody): Promise<SimpleResponse<null>>

Parâmetros:

NomeTipoDescrição
corpoRichInboxIdsBodyObjeto com ids: matriz de IDs de mensagem (ObjectIds do MongoDB). Deve conter pelo menos 1 ID.

Retorna:

TipoDescrição
Promise<SimpleResponse<null>>ok: true em 204 No Content; ok: false com error em 400 ou 500.

Respostas (API):

StatusDescrição
204 No ContentMensagens excluídas com sucesso.
400 Bad RequestCorpo da solicitação ou IDs de mensagem inválidos. Esquema do corpo da resposta: any.
500 Erro interno do servidorProblemas de conexão com o banco de dados ou erro de exclusão. Esquema do corpo da resposta: any.

Exemplo:

const result = await Crm.richInboxDeleteMessages({ ids: ['msgId1', 'msgId2'] });
if (result.ok) {
console.log('Mensagens excluídas');
} else {
console.error('Exclusão falhou:', result.error);
}

richInboxGetAllCounts

Retorna todas as contagens de mensagens para o jogador atual (lidas, não lidas, favoritas, não favoritas, todas).

Assinatura:

richInboxGetAllCounts(): Promise<SimpleResponse<RichInboxAllCountsResponse>>

Retorna:

TipoDescrição
Promise<SimpleResponse<RichInboxAllCountsResponse>>Em caso de sucesso, data contém playerId, read, unread, favorite, unfavorite, all.

Respostas (API):

StatusDescrição
200 OKContagens de mensagens recuperadas com sucesso. Esquema: playerId (string, obrigatório), read (integer, obrigatório), unread (integer, obrigatório), favorite (integer, obrigatório), unfavorite (integer, obrigatório), all (integer, obrigatório).
500 Erro interno do servidorProblemas de conexão com o banco de dados ou erro de consulta. Esquema do corpo da resposta: any.

Esquema 200 OK:

PropriedadeTipoObrigatórioDescrição
playerIdstringSimJogador.
readintegerSimContagem de mensagens lidas.
unreadintegerSimContagem de mensagens não lidas.
favoriteintegerSimContagem de mensagens favoritas.
unfavoriteintegerSimContagem de mensagens não favoritas.
allintegerSimContagem total de todas as mensagens.

Exemplo:

const result = await Crm.richInboxGetAllCounts();
if (result.ok) {
console.log('Não lidas:', result.data.unread, 'Total:', result.data.all);
}

richInboxGetList

Recupera uma lista paginada de mensagens da caixa de entrada do jogador autenticado.

Assinatura:

richInboxGetList(params?: RichInboxListParams): Promise<SimpleResponse<PaginationResponse<Record<string, unknown>[]>>>

Parâmetros de Consulta:

NomeTipoPadrãoDescrição
isReadbooleanFiltrar por status de leitura (true/false).
isFavoritebooleanFiltrar por status de favoritos (true/false).
pageinteger1Número da página para paginação. Valores possíveis: ≥ 1.
limitinteger30Número de itens por página. Valores possíveis: ≥ 1.
searchstringTermo de pesquisa para filtrar mensagens pelo título ou conteúdo da mensagem.

Retorna:

TipoDescrição
Promise<SimpleResponse<PaginationResponse<...>>>Em caso de sucesso, data é um resultado paginado (veja o esquema de 200 OK abaixo).

Respostas (API):

StatusDescrição
200 OKLista da caixa de entrada recuperada com sucesso. Esquema abaixo.
400 Requisição InválidaParâmetros de consulta inválidos. Esquema do corpo da resposta: any.
500 Erro Interno do ServidorProblemas de conexão com o banco de dados ou erro de consulta. Esquema do corpo da resposta: any.

Esquema 200 OK:

PropriedadeTipoDescrição
docsobject[]Array de objetos de mensagem da caixa de entrada.
totalDocsintegerNúmero total de documentos.
limitintegerLimite por página.
pageintegerNúmero da página atual.
totalPagesintegerNúmero total de páginas.
hasPrevPagebooleanSe há uma página anterior.
hasNextPagebooleanSe há uma próxima página.
prevPageinteger | nullPrevious page number.
nextPageinteger | nullNext page number.

Exemplo:

// Primeira página, 30 por página, apenas não lidos
const result = await Crm.richInboxGetList({ isRead: false, page: 1, limit: 30 });
if (result.ok) {
const { docs, totalDocs, page, totalPages } = result.data;
console.log('Mensagens:', docs, 'Total:', totalDocs);
}

richInboxGetCount

Obtenha a contagem de mensagens para o jogador autenticado filtrado por tipo.

Assinatura:

richInboxGetCount(type: RichInboxMessageCountType): Promise<SimpleResponse<RichInboxCountResponse>>

Parâmetros de Consulta:

NomeTipoObrigatórioDescrição
typestringSimTipo de mensagens para contagem. Possíveis valores: read, unread, favorite, unfavorite, all.

Retorna:

TipoDescrição
Promise<SimpleResponse<RichInboxCountResponse>>Em caso de sucesso, data contém playerId e total (consulte o esquema 200 OK).

Respostas (API):

StatusDescrição
200 OKContagem de mensagens recuperada com sucesso. Esquema abaixo.
400 Bad RequestParâmetro inválido. Esquema do corpo da resposta: any.
500: Erro interno do servidorProblemas na conexão do banco de dados ou erro de consulta. Esquema do corpo da resposta: any.

Esquema 200 OK:

PropriedadeTipoObrigatórioDescrição
playerIdstringSimID do jogador.
totalinteiroSimContagem total de mensagens correspondentes ao tipo.

Exemplo:

const result = await Crm.richInboxGetCount('unread');
if (result.ok) {
console.log('Contagem não lida:', result.data.total);
}

richInboxToggleFavorite

Atualiza o status de favorito de uma ou mais mensagens.

Assinatura:

richInboxToggleFavorite(body: RichInboxToggleFavoriteBody): Promise<SimpleResponse<null>>

Corpo da solicitação (obrigatório):

NomeTipoObrigatórioDescrição
idsmongoid[]SimMatriz de IDs de mensagens a serem atualizadas. Valores possíveis: ≥ 1.
isFavoritebooleanoSimStatus de favorito a ser definido para as mensagens.

Retorna:

TipoDescrição
Promise<SimpleResponse<null>>ok: true em 204 Sem Conteúdo; ok: false com error em 400/500.

Respostas (API):

StatusDescrição
204 Sem ConteúdoStatus de favorito atualizado com êxito.
400 Solicitação InválidaCorpo da solicitação ou IDs de mensagem inválidos. Esquema do corpo da resposta: any.
500 Erro Interno do ServidorProblemas de conexão com o banco de dados ou erro de atualização. Esquema do corpo da resposta: any.

Exemplo:

const result = await Crm.richInboxToggleFavorite({
ids: ['msgId1'],
isFavorite: true,
});
if (result.ok) console.log('Status de favorito atualizado');

richInboxToggleRead

Atualiza o status de leitura de uma ou mais mensagens.

Assinatura:

richInboxToggleRead(body: RichInboxToggleReadBody): Promise<SimpleResponse<null>>

Corpo da solicitação (obrigatório):

NomeTipoObrigatórioDescrição
idsmongoid[]SimMatriz de IDs de mensagens a serem atualizadas. Valores possíveis: ≥ 1.
isReadbooleanoSimStatus de leitura a ser definido para as mensagens.

Retorna:

TipoDescrição
Promise<SimpleResponse<null>>ok: true em 204 Sem Conteúdo; ok: false com error em 400/500.

Respostas (API):

StatusDescrição
204 Sem ConteúdoStatus de leitura atualizado com sucesso.
400 Solicitação InválidaCorpo da solicitação ou IDs de mensagem inválidos. Esquema do corpo da resposta: any.
500 Erro Interno do ServidorProblemas na conexão com o banco de dados ou erro na atualização. Esquema do corpo da resposta: any.

Exemplo:

const result = await Crm.richInboxToggleRead({
ids: ['msgId1', 'msgId2'],
isRead: true,
});
if (result.ok) console.log('Status de leitura atualizado');

Interfaces Relacionadas

OneSignalInAppNotificationSubscription

Interface que representa os detalhes da assinatura para notificações push dentro do aplicativo do OneSignal.

type OneSignalInAppNotificationSubscription = {
appId: string;
subscriptionId: string;
playerId: string;
deviceType: string;
oneSignalId: string;
};
PropriedadeTipoDescrição
appIdTipo stringO ID do aplicativo OneSignal
subscriptionIdTipo stringO identificador de assinatura do OneSignal
playerIdTipo stringO identificador único do jogador
deviceTypeTipo stringO tipo de dispositivo sendo registrado
oneSignalIdTipo stringO identificador único do OneSignal

Interfaces da Caixa de Entrada Enriquecida

Tipo RichInboxMessageCountType

Tipo para o endpoint de contagem: 'read' | 'unread' | 'favorite' | 'unfavorite' | 'all'.

Resposta RichInboxAllCountsResponse

Formato da resposta para richInboxGetAllCounts().

interface RichInboxAllCountsResponse {
playerId: string;
read: number;
unread: number;
favorite: number;
unfavorite: number;
all: number;
}
PropriedadeTipoDescrição
playerIdTipo stringID do jogador
readTipo numberContagem de mensagens lidas
unreadTipo numberContagem de mensagens não lidas
favoriteTipo numberContagem de mensagens marcadas como favoritas
unfavoriteTipo numberContagem de mensagens não marcadas como favoritas
allTipo numberContagem total de todas as mensagens

Resposta RichInboxCountResponse

Formato da resposta para richInboxGetCount(type).

interface RichInboxCountResponse {
playerId: string;
total: number;
}
PropriedadeTipoDescrição
playerIdTipo stringID do jogador
totalTipo numberContagem total para o tipo solicitado

Parâmetros RichInboxListParams

Parâmetros de consulta para richInboxGetList().

interface RichInboxListParams {
isRead?: boolean;
isFavorite?: boolean;
page?: number;
limit?: number;
search?: string;
}
PropriedadeTipoDescrição
isReadboolean (opcional)Filtrar por status de leitura
isFavoriteboolean (opcional)Filtrar por status de favorito
pagenumber (opcional)Número da página (≥ 1, padrão 1)
limitnumber (opcional)Itens por página (≥ 1, padrão 30)
searchstring (opcional)Termo de pesquisa (título ou conteúdo da mensagem)

RichInboxIdsBody

Corpo para excluir e para a matriz de ids nos métodos de alternância.

interface RichInboxIdsBody {
ids: string[];
}
PropriedadeTipoDescrição
idsstring[]Matriz de IDs de mensagens (ObjectIds do MongoDB). Pelo menos 1 obrigatório.

RichInboxToggleFavoriteBody

Corpo para richInboxToggleFavorite().

interface RichInboxToggleFavoriteBody extends RichInboxIdsBody {
isFavorite: boolean;
}
PropriedadeTipoDescrição
idsstring[]Matriz de IDs de mensagens a serem atualizadas
isFavoriteTipo booleanStatus de favorito a ser definido

RichInboxToggleReadBody

Corpo para richInboxToggleRead().

interface RichInboxToggleReadBody extends RichInboxIdsBody {
isRead: boolean;
}
PropriedadeTipoDescrição
idsstring[]Array of message IDs to update
isReadbooleanRead status to set

SimpleResponse

Generic interface representing a simple response from the API.

interface SimpleResponse<T> {
ok: boolean;
error?: ErrorResponse;
data: T | null;
}
PropertyTypeDescrição
okbooleanIndicates if the operation was successful
erroErrorResponse (opcional)Error details if the operation failed
dataT | nullThe response data (null in this case of OneSignal registration)

ErrorResponse

Interface representing an error response from the API.

interface ErrorResponse {
message: string;
details: {
faultCode: number;
fields: {
field: string;
error: string;
}[];
};
request: {
xRequestId: string;
method: string;
headers: Record<string, string>[];
};
timestamp: string;
}
PropertyTypeDescrição
messageTipo stringError message
details.faultCodeTipo numberNumeric code identifying the error
details.fieldsArrayList of field-specific errors
details.fields[].fieldTipo stringName of the field with an error
details.fields[].errorTipo stringError message for the field
request.xRequestIdTipo stringIdentificador da solicitação
request.methodTipo stringMétodo HTTP usado para a solicitação
request.headersArrayCabeçalhos da Solicitação
timestampTipo stringCarimbo de data/hora quando o erro ocorreu

WebPushSubscriptionRequestStatus

Enum que representa os possíveis valores de status retornados pelo método playerRegisterWebPushSubscription.

enum WebPushSubscriptionRequestStatus {
SUCCESS = 'SUCCESS',
ALREADY_GRANTED = 'ALREADY_GRANTED',
MISSING_SERVICE_WORKER = 'MISSING_SERVICE_WORKER',
WEB_PUSH_NOT_SUPPORTED = 'WEB_PUSH_NOT_SUPPORTED',
WEB_PUSH_PERMISSION_DENIED = 'WEB_PUSH_PERMISSION_DENIED',
WEB_PUSH_PERMISSION_CANCELLED = 'WEB_PUSH_PERMISSION_CANCELLED',
ERROR = 'ERROR',
}
ValorDescrição
SUCCESSO jogador registrou-se com sucesso para notificações push da web.
ALREADY_GRANTEDO jogador já concedeu permissão para notificações push da web.
MISSING_SERVICE_WORKERO serviço worker necessário para as notificações push da web está ausente.
WEB_PUSH_NOT_SUPPORTEDAs notificações push da web não são suportadas no navegador atual.
WEB_PUSH_PERMISSION_DENIEDO jogador negou permissão para notificações push da web.
WEB_PUSH_PERMISSION_CANCELLEDO jogador cancelou a solicitação de permissão para notificações push da web.
ERROROcorreu um erro durante o processo de assinatura de notificações push da web.

OnsiteVariantEnum

Enum que representa as diferentes variantes de exibição para notificações no local.

enum OnsiteVariantEnum {
DEFAULT = 'DEFAULT',
TITLE = 'TITLE',
IMAGE_TOP = 'IMAGE_TOP',
IMAGE_RIGHT = 'IMAGE_RIGHT',
IMAGE_LEFT = 'IMAGE_LEFT',
}
ValorDescrição
DEFAULTVariante de exibição padrão para notificações no local.
TITLEVariante de exibição somente com título para notificações no local.
IMAGE_TOPVariante de exibição com imagem no topo para notificações no local.
IMAGE_RIGHTVariante de exibição com imagem à direita para notificações no local.
IMAGE_LEFTVariante de exibição com imagem à esquerda para notificações no local.

AnalyticsTrackingType

Enum que representa os diferentes tipos de rastreamento de análises.

enum AnalyticsTrackingType {
DELIVERED = 'DELIVERED',
OPENED = 'OPENED',
CLICKED = 'CLICKED',
ERROR = 'ERROR',
}
ValorDescrição
DELIVEREDRastreamento para quando uma notificação é entregue.
OPENEDRastreamento para quando uma notificação é aberta.
CLICKEDRastreamento para quando uma notificação é clicada.
ERRORRastreamento para quando ocorre um erro com uma notificação.

AnalyticsTrackingChannel

Enum que representa os diferentes canais para rastreamento de análises.

enum AnalyticsTrackingChannel {
ON_SITE = 'ON_SITE',
WEB_PUSH = 'WEB_PUSH',
}
ValorDescrição
ON_SITERastreamento de análises para notificações no local.
WEB_PUSHRastreamento de análises para notificações push da web.

OnSiteNotificationEventData

Interface para dados de evento de notificação no local.

interface OnSiteNotificationEventData extends BaseEventData {
msg: {
type: OnsiteVariantEnum;
contentHtml: string;
language: string;
};
playerId: string;
}
PropriedadeTipoObrigatórioDescrição
msg{ type: OnsiteVariantEnum; contentHtml: string; language: string; }SimConteúdo da mensagem para a notificação no local.
msg.typeOnsiteVariantEnumSimVariante de exibição para a notificação no local.
msg.contentHtmlTipo stringSimConteúdo HTML para a notificação no local.
msg.languageTipo stringSimIdioma do conteúdo da notificação no local.
playerIdTipo stringSimID do jogador que recebe a notificação.

AnalyticsTrackingEventEmitter

Interface para emissores de eventos de rastreamento de análise.

interface AnalyticsTrackingEventEmitter {
message: InternalRawEvent<'messageGateway:on:sendOnSiteNotification'>;
trackingType: AnalyticsTrackingType;
channel: AnalyticsTrackingChannel;
errorDetail?: {
code: string;
description?: string;
metadata: Record<string, unknown>;
};
}
PropriedadeTipoObrigatórioDescrição
messageInternalRawEvent<'messageGateway:on:sendOnSiteNotification'>SimO evento de mensagem sendo rastreado.
trackingTypeAnalyticsTrackingTypeSimO tipo de rastreamento (ENTREGUE, ABERTO, CLICADO, ERRO).
channelAnalyticsTrackingChannelSimO canal sendo rastreado (NO_SITE, WEB_PUSH).
errorDetail{ code: string; description?: string; metadata: Record<string, unknown>; }NãoDetalhes sobre qualquer erro que tenha ocorrido.
errorDetail.codeTipo stringSimUm código de erro único para identificar o problema (por exemplo, PUSH_001).
errorDetail.descriptionTipo stringNãoUma descrição legível para humanos do erro a ser exibida na interface do Analytics.
errorDetail.metadataRecord<string, unknown>SimInformações de erro gerais de uma maneira mais técnica para auditoria interna.