Pular para o conteúdo principal

Módulo CRM

El Módulo CRM brinda funcionalidad para gestionar notificaciones push web, notificaciones in-app y Rich Inbox en el SDK Web Client de Gamanza Engage. Permite a los desarrolladores registrar jugadores para notificaciones push web, gestionar solicitudes de permiso de notificación, manejar notificaciones push in-app de OneSignal y gestionar mensajes de bandeja de entrada (listar, contar, alternar lectura/favorito, eliminar).

Acceso al Módulo

El módulo CrmModule se inicializa internamente por el SDK y no debe ser instanciado directamente. Se puede acceder a través de la instancia principal del SDK.

// Ejemplo de acceso al módulo CrmModule a través del SDK
const { Crm } = GamanzaEngageWebClientSDK.getInstance();

Métodos

registroDelSuscriptorDeNotificacionesWebDelJugador

Registra al jugador autenticado actual para Notificaciones Push Web alimentadas por el CRM de Gamanza Engage. Esta función registra el service worker, valida si el agente de usuario del jugador es compatible con push y además valida si los permisos para Notificaciones han sido otorgados o denegados.

Firma:

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

Retorna:

TipoDescripción
Promise<{ status: WebPushSubscriptionRequestStatus }>Una promesa que se resuelve a un objeto que contiene el estado de la solicitud de suscripción a notificaciones push web.

Ejemplo:

// Registrar para notificaciones push web
const handleRequestPermissionsClick = async (evt) => {
evt.preventDefault();
// Esta llamada muestra la solicitud de permisos de notificaciones del agente de usuario nativo
const result = await Crm.playerRegisterWebPushSubscription();
if (result.status === WebPushSubscriptionRequestStatus.SUCCESS) {
alert('Felicidades, estás suscrito para recibir Notificaciones Push');
} else if (result.status === WebPushSubscriptionRequestStatus.WEB_PUSH_NOT_SUPPORTED) {
alert('Las Notificaciones Push Web no son compatibles en este navegador');
} else if (result.status === WebPushSubscriptionRequestStatus.WEB_PUSH_PERMISSION_DENIED) {
alert('Se denegó el permiso para recibir notificaciones');
}
};

// Adjuntar a un evento de clic de botón
document.getElementById('notification-permission-btn').addEventListener('click', handleRequestPermissionsClick);

Notas:

  • Para Safari, la solicitud debe estar detrás de una interacción del usuario. Cuando el usuario complete el gesto, llame al método de suscripción push de inmediato desde el código del controlador de eventos del gesto.
  • Para ver los requisitos, consulte la documentación de configuración de Web Push.

debesMostrarElBannerDePermisosDeNotificación

Función de ayuda para permitirle decidir cuándo mostrar el banner de solicitud de permisos para Notificaciones Push Web. Esto es particularmente útil para Safari, donde el método de suscripción push debe llamarse de inmediato desde el código del controlador de eventos de un gesto de usuario.

Firma:

debesMostrarElBannerDePermisosDeNotificación(días: number = 30, anular: boolean = true): Promise<boolean>

Parámetros:

NombreTipoPredeterminadoDescripción
díasnumber30Número de días para esperar antes de mostrar el banner nuevamente. El sistema almacena este valor en el almacenamiento persistente.
anularbooleantrueDefine si quieres escribir en el almacenamiento de persistencia la próxima vez que la función debería devolver verdadero para el jugador actual.

Devuelve:

TipoDescripción
Promise<boolean>Una promesa que se resuelve en un booleano que indica si se debe mostrar el banner de solicitud de permisos de notificación.

Ejemplo:

Comprobación automática y anulación de la siguiente comprobación:

// Comprueba si debemos mostrar el banner de permisos de notificación
if (await Crm.shouldShowNotificationRequestPermissionsBanner(5)) {
// Muestra el banner en la interfaz de usuario
showNotificationBanner();
}

Control de anulación en persistencia:

// Comprueba si debemos mostrar el banner sin actualizar la persistencia
if (await Crm.shouldShowNotificationRequestPermissionsBanner(5, false)) {
// Muestra el banner en la interfaz de usuario
showNotificationBanner();
}

// Controlador para que el jugador cierre el banner
const onCloseBannerClick = async (evt) => {
evt.preventDefault();
hideNotificationBanner();

// Actualiza la próxima vez que se debe mostrar el banner a 5 días
await Crm.shouldShowNotificationRequestPermissionsBanner(5, true);
};

suscripciónDeNotificacionesPushEnAplicaciónDelJugadorOneSignal

Registra al jugador autenticado actual para las notificaciones push in-app de OneSignal. Este método permite registrar a un jugador para recibir notificaciones push a través de OneSignal dentro de la aplicación.

Firma:

suscripciónDeNotificacionesPushEnAplicaciónDelJugadorOneSignal(subs: OneSignalInAppNotificationSubscription): Promise<SimpleResponse<null>>

Parámetros:

NombreTipoDescripción
subsOneSignalInAppNotificationSubscriptionLos detalles de suscripción de OneSignal.

Devuelve:

TipoDescripción
Promise<SimpleResponse<null>>Una promesa que se resuelve en un objeto SimpleResponse que indica el éxito o el fracaso del registro.

Ejemplo:

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

const result = await Crm.suscripciónDeNotificacionesPushEnAplicaciónDelJugadorOneSignal(subscription);
if (result.ok) {
console.log("Successfully registered for OneSignal notifications");
} else {
console.error("Failed to register for OneSignal notifications:", result.error);
}

Bandeja de entrada enriquecida

La API de Bandeja de entrada enriquecida permite enumerar, contar y administrar los mensajes de la bandeja de entrada (estado de lectura/favorito, eliminar). Todos los métodos utilizan la ruta base /api/rich-inbox/v1 y devuelven SimpleResponse<T>.

eliminarMensajesDeInboxRico

Elimina los mensajes por sus IDs.

Firma:

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

Parámetros:

NombreTipoDescripción
bodyRichInboxIdsBodyObjeto con ids: array de IDs de mensajes (MongoDB ObjectIds). Debe contener al menos 1 ID.

Devuelve:

TipoDescripción
Promise<SimpleResponse<null>>ok: true en 204 No Content; ok: false con error en 400 o 500.

Respuestas (API):

EstadoDescripción
204 No ContentMensajes eliminados correctamente.
400 Bad RequestCuerpo de solicitud o IDs de mensaje no válidos. Esquema del cuerpo de respuesta: any.
500 Internal Server ErrorProblemas de conexión a la base de datos o error de eliminación. Esquema del cuerpo de respuesta: any.

Ejemplo:

const result = await Crm.richInboxDeleteMessages({ ids: ['msgId1', 'msgId2'] });
if (result.ok) {
console.log('Mensajes eliminados');
} else {
console.error('Error al eliminar:', result.error);
}

obtenerTodasLasCuentasDeInboxRico

Devuelve todos los conteos de mensajes para el jugador actual (leídos, no leídos, favoritos, no favoritos, todos).

Firma:

obtenerTodasLasCuentasDeInboxRico(): Promise<SimpleResponse<RichInboxAllCountsResponse>>

Devuelve:

TipoDescripción
Promise<SimpleResponse<RichInboxAllCountsResponse>>En caso de éxito, data contiene playerId, read, unread, favorite, unfavorite, all.

Respuestas (API):

EstadoDescripción
200 OKConteos de mensaje recuperados con éxito. Esquema: playerId (cadena, requerido), read (entero, requerido), unread (entero, requerido), favorite (entero, requerido), unfavorite (entero, requerido), all (entero, requerido).
500 Internal Server ErrorProblemas de conexión a la base de datos o error de consulta. Esquema del cuerpo de respuesta: any.

Esquema 200 OK:

PropiedadTipoRequeridoDescripción
playerIdcadenaID de jugador.
leerenteroRecuento de mensajes leídos.
no leídoenteroRecuento de mensajes no leídos.
favoritoenteroRecuento de mensajes favoritos.
no favoritoenteroRecuento de mensajes no favoritos.
todosenteroRecuento total de todos los mensajes.

Ejemplo:

const result = await Crm.richInboxGetAllCounts();
if (result.ok) {
console.log('No leídos:', result.data.unread, 'Total:', result.data.all);
}

obtenerListaDeInboxRico

Recupera una lista paginada de mensajes de bandeja de entrada para el jugador autenticado.

Firma:

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

Parámetros de consulta:

NombreTipoPredeterminadoDescripción
esLeídobooleanoFiltrar por estado de lectura (verdadero/falso).
esFavoritobooleanoFiltrar por estado de favorito (verdadero/falso).
páginaentero1Número de página para paginación. Valores posibles: ≥ 1.
límiteentero30Número de elementos por página. Valores posibles: ≥ 1.
searchcadenaTérmino de búsqueda para filtrar mensajes por título o contenido del mensaje.

Devuelve:

TipoDescripción
Promise<SimpleResponse<PaginationResponse<...>>>En caso de éxito, data es un resultado paginado (ver el esquema de 200 OK a continuación).

Respuestas (API):

EstadoDescripción
200 OKLa lista de bandeja de entrada se recuperó correctamente. Esquema a continuación.
400 Bad RequestParámetros de consulta no válidos. Esquema del cuerpo de respuesta: any.
500 Internal Server ErrorProblemas de conexión a la base de datos o error de consulta. Esquema del cuerpo de respuesta: any.

Esquema 200 OK:

PropiedadTipoDescripción
docsobjeto[]Array de objetos de mensaje de bandeja de entrada.
totalDocsenteroNúmero total de documentos.
limitenteroLímite por página.
pageenteroNúmero de página actual.
totalPagesenteroNúmero total de páginas.
hasPrevPagebooleanoSi hay una página anterior.
hasNextPagebooleanoSi hay una página siguiente.
anterior a la páginaentero | nuloNúmero de la página anterior.
siguiente páginaentero | nuloNúmero de la siguiente página.

Ejemplo:

// Primera página, 30 por página, solo no leídos
const result = await Crm.richInboxGetList({ isRead: false, page: 1, limit: 30 });
if (result.ok) {
const { docs, totalDocs, page, totalPages } = result.data;
console.log('Mensajes:', docs, 'Total:', totalDocs);
}

obtenerCuentaDeInboxRico

Obtener el recuento de mensajes para el jugador autenticado filtrado por tipo.

Firma:

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

Parámetros de consulta:

NombreTipoRequeridoDescripción
typecadenaTipo de mensajes a contar. Valores posibles: read, unread, favorite, unfavorite, all.

Devuelve:

TipoDescripción
Promise<SimpleResponse<RichInboxCountResponse>>En caso de éxito, data contiene playerId y total (ver esquema 200 OK).

Respuestas (API):

EstadoDescripción
200 OKRecuento de mensajes recuperado con éxito. Esquema a continuación.
400 Bad RequestParámetro de tipo no válido. Esquema del cuerpo de respuesta: any.
500 Internal Server ErrorProblemas de conexión a la base de datos o error de consulta. Esquema del cuerpo de respuesta: any.

Esquema 200 OK:

PropiedadTipoRequeridoDescripción
playerIdcadenaID del jugador.
totalenteroRecuento total de mensajes que coinciden con el tipo.

Ejemplo:

const result = await Crm.richInboxGetCount('unread');
if (result.ok) {
console.log('Recuento no leído:', result.data.total);
}

richInboxToggleFavorite

Actualizar el estado de favorito de uno o más mensajes.

Firma:

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

Cuerpo de la solicitud (obligatorio):

NombreTipoRequeridoDescripción
idsmongoid[]Matriz de ID de mensajes para actualizar. Valores posibles: ≥ 1.
isFavoritebooleanoEstado de favorito para establecer para los mensajes.

Devuelve:

TipoDescripción
Promise<SimpleResponse<null>>ok: true en 204 No Contenido; ok: false con error en 400/500.

Respuestas (API):

EstadoDescripción
204 No ContenidoEstado de favorito actualizado correctamente.
400 Solicitud ErróneaCuerpo de solicitud o ID de mensaje no válidos. Esquema del cuerpo de respuesta: any.
500 Error Interno del ServidorProblemas de conexión a la base de datos o error de actualización. Esquema del cuerpo de respuesta: any.

Ejemplo:

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

richInboxToggleRead

Actualizar el estado de lectura de uno o más mensajes.

Firma:

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

Cuerpo de la solicitud (obligatorio):

NombreTipoRequeridoDescripción
idsmongoid[]Array de identificadores de mensajes para actualizar. Valores posibles: ≥ 1.
isReadbooleanoEstablecer estado de lectura para los mensajes.

Devuelve:

TipoDescripción
Promise<SimpleResponse<null>>ok: true en 204 No Content; ok: false con error en 400/500.

Respuestas (API):

EstadoDescripción
204 No ContentActualizado con éxito el estado de lectura.
400 Bad RequestCuerpo de solicitud o identificadores de mensaje no válidos. Esquema de cuerpo de respuesta: any.
500 Internal Server ErrorProblemas de conexión a la base de datos o error de actualización. Esquema de cuerpo de respuesta: any.

Ejemplo:

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

Interfaces Relacionadas

OneSignalInAppNotificationSubscription

Interfaz que representa los detalles de suscripción para las notificaciones push de OneSignal In-App.

type OneSignalInAppNotificationSubscription = {
appId: string;
subscriptionId: string;
playerId: string;
deviceType: string;
oneSignalId: string;
};
PropiedadTipoDescripción
appIdstringEl ID de la aplicación de OneSignal
subscriptionIdstringEl identificador de suscripción de OneSignal
playerIdstringEl identificador único del jugador
tipo de dispositivocadenaEl tipo de dispositivo que se está registrando
oneSignalIdcadenaEl identificador único de OneSignal

Interfaces de Rich Inbox

Tipo de RichInboxMessageCountType

Tipo para el punto final de recuento: 'read' | 'unread' | 'favorite' | 'unfavorite' | 'all'.

RichInboxAllCountsResponse

Forma de respuesta para richInboxGetAllCounts().

interfaz RichInboxAllCountsResponse {
playerId: cadena;
read: número;
unread: número;
favorite: número;
unfavorite: número;
all: número;
}
PropiedadTipoDescripción
playerIdcadenaID de jugador
readnúmeroRecuento de mensajes leídos
unreadnúmeroRecuento de mensajes no leídos
favoritenúmeroRecuento de mensajes favoritos
unfavoritenúmeroRecuento de mensajes no favoritos
allnúmeroRecuento total de todos los mensajes

RichInboxCountResponse

Forma de respuesta para richInboxGetCount(type).

interfaz RichInboxCountResponse {
playerId: cadena;
total: número;
}
PropiedadTipoDescripción
playerIdcadenaID de jugador
totalnúmeroRecuento total para el tipo solicitado

RichInboxListParams

Parámetros de consulta para richInboxGetList().

interfaz RichInboxListParams {
isRead?: boolean;
isFavorite?: boolean;
page?: number;
limit?: number;
search?: string;
}
PropiedadTipoDescripción
isReadboolean (opcional)Filtrar por estado de lectura
isFavoriteboolean (opcional)Filtrar por estado de favorito
pagenumber (opcional)Número de página (≥ 1, predeterminado 1)
limitnumber (opcional)Elementos por página (≥ 1, predeterminado 30)
searchstring (opcional)Término de búsqueda (título o contenido del mensaje)

RichInboxIdsBody

Cuerpo para eliminar y para la matriz de identificadores en los métodos de alternancia.

interfaz RichInboxIdsBody {
ids: string[];
}
PropiedadTipoDescripción
idsstring[]Matriz de identificadores de mensajes (MongoDB ObjectIds). Se requiere al menos 1.

RichInboxToggleFavoriteBody

Cuerpo para richInboxToggleFavorite().

interfaz RichInboxToggleFavoriteBody extends RichInboxIdsBody {
isFavorite: boolean;
}
PropiedadTipoDescripción
idsstring[]Matriz de identificadores de mensajes para actualizar
isFavoritebooleanEstado de favorito a establecer

RichInboxToggleReadBody

Cuerpo para richInboxToggleRead().

interfaz RichInboxToggleReadBody extends RichInboxIdsBody {
isRead: boolean;
}
PropiedadTipoDescripción
idsstring[]Matriz de ID de mensajes a actualizar
isReadbooleanEstado de lectura a establecer

SimpleResponse

Interfaz genérica que representa una respuesta simple de la API.

interfaz SimpleResponse<T> {
ok: boolean;
error?: ErrorResponse;
data: T | null;
}
PropiedadTipoDescripción
okbooleanIndica si la operación fue exitosa
errorErrorResponse (opcional)Detalles del error si la operación falló
dataT | nullLos datos de respuesta (nulo en este caso de registro de OneSignal)

ErrorResponse

Interfaz que representa una respuesta de error de la API.

interfaz ErrorResponse {
message: string;
details: {
faultCode: number;
fields: {
field: string;
error: string;
}[];
};
request: {
xRequestId: string;
method: string;
headers: Record<string, string>[];
};
timestamp: string;
}
PropiedadTipoDescripción
messagestringMensaje de error
details.faultCodenumberCódigo numérico que identifica el error
details.fieldsArrayLista de errores específicos del campo
details.fields[].fieldstringNombre del campo con un error
details.fields[].errorstringMensaje de error para el campo
request.xRequestIdstringIdentificador de solicitud
request.methodcadenaMétodo HTTP utilizado para la solicitud
request.headersMatrizEncabezados de solicitud
timestampcadenaMarca de tiempo cuando ocurrió el error

WebPushSubscriptionRequestStatus

Enum que representa los posibles valores de estado devueltos por el 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',
}
ValorDescripción
SUCCESSEl jugador se ha registrado correctamente para las notificaciones push web.
ALREADY_GRANTEDEl jugador ya ha otorgado permiso para las notificaciones push web.
MISSING_SERVICE_WORKERFalta el service worker requerido para las notificaciones push web.
WEB_PUSH_NOT_SUPPORTEDLas notificaciones push web no son compatibles con el navegador actual.
WEB_PUSH_PERMISSION_DENIEDEl jugador ha denegado el permiso para las notificaciones push web.
WEB_PUSH_PERMISSION_CANCELLEDEl jugador canceló la solicitud de permiso para las notificaciones push web.
ERROROcurrió un error durante el proceso de suscripción push web.

OnsiteVariantEnum

Enum que representa las diferentes variantes de visualización para las notificaciones in situ.

enum OnsiteVariantEnum {
DEFAULT = 'DEFAULT',
TITLE = 'TITLE',
IMAGE_TOP = 'IMAGE_TOP',
IMAGE_RIGHT = 'IMAGE_RIGHT',
IMAGE_LEFT = 'IMAGE_LEFT',
}
ValorDescripción
DEFAULTVariante de visualización predeterminada para las notificaciones in situ.
TITLEVariante de visualización solo con título para las notificaciones in situ.
IMAGE_TOPVariante de visualización con imagen arriba para las notificaciones in situ.
IMAGE_RIGHTVariante de visualización con imagen a la derecha para las notificaciones in situ.
IMAGE_LEFTVariante de visualización con imagen a la izquierda para las notificaciones in situ.

AnalyticsTrackingType

Enum que representa los diferentes tipos de seguimiento de análisis.

enum AnalyticsTrackingType {
ENTREGADO = 'ENTREGADO',
ABIERTO = 'ABIERTO',
CLIQUEADO = 'CLIQUEADO',
ERROR = 'ERROR',
}
ValorDescripción
ENTREGADOSeguimiento cuando se entrega una notificación.
ABIERTOSeguimiento cuando se abre una notificación.
CLIQUEADOSeguimiento cuando se cliquea una notificación.
ERRORSeguimiento cuando ocurre un error con una notificación.

AnalyticsTrackingChannel

Enum que representa los diferentes canales para el seguimiento de análisis.

enum AnalyticsTrackingChannel {
EN_SITIO = 'EN_SITIO',
WEB_PUSH = 'WEB_PUSH',
}
ValorDescripción
EN_SITIOSeguimiento de análisis para notificaciones en sitio.
WEB_PUSHSeguimiento de análisis para notificaciones push web.

OnSiteNotificationEventData

Interfaz para datos de eventos de notificación en sitio.

interface OnSiteNotificationEventData extends BaseEventData {
msg: {
type: OnsiteVariantEnum;
contentHtml: string;
language: string;
};
playerId: string;
}
PropiedadTipoRequeridoDescripción
msg{ type: OnsiteVariantEnum; contentHtml: string; language: string; }Contenido del mensaje para la notificación en sitio.
msg.typeOnsiteVariantEnumVariante de visualización para la notificación en sitio.
msg.contentHtmlstringContenido HTML para la notificación en sitio.
msg.languagestringIdioma del contenido de la notificación en sitio.
playerIdstringID del jugador que recibe la notificación.

AnalyticsTrackingEventEmitter

Interfaz para emisores de eventos de seguimiento de análisis.

interfaz AnalyticsTrackingEventEmitter {
message: InternalRawEvent<'messageGateway:on:sendOnSiteNotification'>;
trackingType: AnalyticsTrackingType;
channel: AnalyticsTrackingChannel;
errorDetail?: {
code: string;
description?: string;
metadata: Record<string, unknown>;
};
}
PropiedadTipoRequeridoDescripción
messageInternalRawEvent<'messageGateway:on:sendOnSiteNotification'>El evento de mensaje que se está rastreando.
trackingTypeAnalyticsTrackingTypeEl tipo de seguimiento (ENTREGADO, ABIERTO, HECHO CLIC, ERROR).
channelAnalyticsTrackingChannelEl canal que se está rastreando (EN_SITIO, PUSH_WEB).
errorDetail{ code: string; description?: string; metadata: Record<string, unknown>; }NoDetalles sobre cualquier error que haya ocurrido.
errorDetail.codestringUn código de error único para identificar el problema (por ejemplo, PUSH_001).
errorDetail.descriptionstringNoUna descripción legible por humanos del error que se mostrará en la interfaz de usuario de Análisis.
errorDetail.metadataRecord<string, unknown>Información de error general de una manera más técnica para auditoría interna.