@octovise/react-native-sdk

SDK oficial de Octovise para React Native. Renderea mensajes in-app (modal / toast) en la app del cliente y reporta engagement al backend.

v1.0 incluye solo in-app messaging. Push notifications llegan en v1.1 — el código nativo ya está en el paquete pero deshabilitado por default.

Instalación

npm install @octovise/react-native-sdk
# o
yarn add @octovise/react-native-sdk

Peer dependencies (probablemente ya las tenés):

{
  "react": ">=18",
  "react-native": ">=0.72"
}

No requiere Firebase, App Group, ni configuración nativa. Es JS-only.

Quickstart

1. Envolvé la app con <OctoProvider>

// App.tsx
import { OctoProvider } from '@octovise/react-native-sdk'

export default function App() {
  return (
    <OctoProvider>
      <RestOfYourApp />
    </OctoProvider>
  )
}

2. Llamá init() después del login

import { init } from '@octovise/react-native-sdk'
import { useNavigation } from '@react-navigation/native'

function LoggedInScreen() {
  const nav = useNavigation()

  useEffect(() => {
    init({
      apiKey: 'pk_live_xxxxxxxxxxxx',
      userId: currentUser.id,        // tu ID interno del usuario (number o string)
      onCTA: (url) => nav.navigate(url),  // navegación cuando el user toca el CTA
    })
  }, [currentUser])

  return <YourScreen />
}

3. Listo

El SDK consulta /check automáticamente, renderea el mensaje que corresponda y reporta los eventos al backend.

API

init(config)

Arranca la SDK y dispara un primer /check. Tiene un cooldown de 5 minutos para evitar requests redundantes en re-renders / re-mounts. Re-chequea automáticamente cuando la app vuelve del background (si pasaron más de 5 min).

type OctoRNConfig = {
  apiKey: string                   // Backoffice → Settings → SDK
  userId: number | string          // tu user_id interno
  userHash?: string                // requerido si la SDK key tiene HMAC enforced — HMAC-SHA256(userId, signing_secret)
  baseUrl?: string                 // default: https://sdk-api.octovise.com.ar
  onCTA?: (url: string) => void    // navegación al tap del CTA
  registerPushToken?: boolean      // v1.1+ — default: false (in-app only)
}

close()

Cierra cualquier mensaje on-screen y resetea el cooldown. Llamar al logout.

forceCheck({ ignoreDedup? })

Dispara un /check saltando el cooldown. Pensado para acciones explícitas del usuario (botón "Actualizar mensajes"). En producción típica, no la necesitás — init() + el listener de foreground alcanzan.

triggerTestInApp()

Para QA. Pide al backend que encole una campaña de prueba para el usuario actual y la muestra inmediatamente. No usar en producción.

Tipos de mensaje

El backend determina qué se renderea — vos no construís los mensajes desde el SDK. Pero estos son los layouts que tu Backoffice puede configurar:

| Layout | Cuándo | |---|---| | modal | Centrado, fondo oscuro, requiere atención. Para promos importantes | | toast | Esquina/borde, discreto. Para tips, recordatorios, novedades |

Cada uno soporta variantes con/sin imagen, modos de tap, posición desktop y mobile, colores custom, etc. Todo se configura en el Backoffice → Campañas → In-App.

Modos de click

| click_mode | UI | Tap en card | Caso de uso | |---|---|---|---| | cta (default) | Botón CTA visible | Ignorado | Promos clásicas con botón claro | | full | Sin botón | Dispara CTA + navega | Banner-style card que ES el CTA | | none | Sin botón, sin CTA destino | Registra engagement (no navega) | Anuncios informativos con tracking |

Métricas reportadas

Cada interacción genera un evento que el SDK manda al backend (con fetch(..., { keepalive: true }), así sobrevive navegaciones inmediatas post-CTA):

• impression — al mostrarse el mensaje
• click — al tocar el CTA (o card en modo full/none)
• dismiss — al cerrar (X / "Ahora no" / backdrop)

Metadata incluida: duration_ms, time_to_first_interaction_ms (null si solo cerró), device, platform (ios/android), image_loaded, close_method.

Cooldown y dedup

• Cooldown de init: ignora init() consecutivos dentro de 5 minutos. Re-mounts y re-renders son seguros.
• Dedup por mensaje: el mismo msg.id no se muestra dos veces consecutivas, incluso si /check lo devuelve de nuevo.
• Foreground listener: cuando la app vuelve del background y pasaron >5 min desde el último init, re-chequea automáticamente.

Privacidad

El SDK colecta:

• ID interno de usuario (provisto por vos)
• URL/page de la app donde se mostró el mensaje (si la pasás)
• Tipo de device (ios/android) — no IDFA / Advertising ID
• Tiempos de interacción

NO colecta: ubicación, contactos, biometría, IDs de publicidad, ni nada que requiera permisos especiales del sistema operativo.

Roadmap

• v1.1 — Push notifications (Firebase + Apple Push). Activable con registerPushToken: true. Requiere setup adicional del cliente.
• v1.2 — Soporte para New Architecture (TurboModules/Fabric).
• v2 — Encuestas, NPS inline, deep-link routing avanzado.

Soporte

Para issues con la SDK, problemas de integración o bugs: GitHub Issues.

Para temas del producto Octovise (configurar campañas, dudas de billing, etc.): Backoffice → Soporte.

License

MIT © 2026 Octovise Argentina S.A.S.