@octovise/react-native-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+Notas de versión del SDK de Octovise. Versionado con [SemVer](https://semver.org/).
+
+Impacto de cada cambio:
+
+- **Requiere cambios** — tenés que tocar tu código al actualizar.
+- **Requiere acción** — un paso sin código (p. ej. actualizar una configuración).
+- *(sin etiqueta)* — actualización directa, sin acción.
+
+## [Unreleased]
+
+## [1.0.0] — 2026-07-10
+
+- Primera versión estable.
+
+## [0.1.0-beta.1] — 2026-06-07
+
+Primer release público beta. **In-app messaging únicamente.** Push notifications quedan para `v1.1`.
+
+### Added
+- `OctoProvider`, `init`, `close`, `forceCheck`, `triggerTestInApp` — superficie pública del SDK
+- Layouts: `modal` y `toast`, con variantes `text` / `image` / `both`
+- `click_mode`: `cta` (default), `full` (toda la card es CTA), `none` (read-only con señal de engagement)
+- Posicionamiento responsive: `position` (desktop) + `mobile_position` (top/center/bottom)
+- Soporte de tema: `colors.primary` / `background` / `text`, `size`, `text_size`, `text_align`
+- Image preload con `Image.prefetch` — skip silencioso si la imagen falla
+- Cooldown de 5 minutos entre `init` consecutivos
+- Dedup por `msg.id` para evitar mostrar el mismo mensaje dos veces seguidas
+- Re-check al volver del foreground (si el cooldown expiró)
+- Tracking de eventos `impression` / `click` / `dismiss` con metadata: `duration_ms`, `time_to_first_interaction_ms`, `page_url`, `device`, `platform`, `image_loaded`, `close_method`
+- `time_to_first_interaction_ms` solo se completa con engagement real (CTA tap o card tap en modos `full` / `none`); dismissing deja la métrica como `null`
+- Botón de cierre con alto contraste (dark backdrop + glyph blanco + sombra) — legible sobre cualquier imagen subyacente
+- Compatible con `keepalive` fetch para que los eventos sobrevivan navegación inmediata post-CTA
+
+### Backend requirements
+- Requiere [`@octovise-sdk-api`](https://sdk.octovise.com.ar) (servidor de Octovise). Ver [Backoffice → Settings → SDK](https://backoffice.octovise.com.ar) para conseguir tu `apiKey`.
+- Para HMAC de userHash, ver la sección de seguridad en el README.
+
+### Known limitations
+- Sin push notifications. El código nativo (iOS Notification Service Extension + Android FirebaseMessagingService) está incluido pero deshabilitado vía `react-native.config.js` (`platforms: null`). Se activa en `v1.1`.
+- Sin React Native New Architecture (TurboModules / Fabric) — no requerido en v1 porque la SDK es JS-only.
+- Sin Expo managed workflow oficialmente probado (debería andar, pero E2E pendiente).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Octovise Argentina S.A.S.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# @octovise/react-native-sdk
+
+[![npm](https://img.shields.io/npm/v/@octovise/react-native-sdk?label=npm)](https://www.npmjs.com/package/@octovise/react-native-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20Android-blue)](#)
+
+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
+
+```bash
+npm install @octovise/react-native-sdk
+# o
+yarn add @octovise/react-native-sdk
+```
+
+**Peer dependencies** (probablemente ya las tenés):
+
+```json
+{
+  "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>`
+
+```tsx
+// App.tsx
+import { OctoProvider } from '@octovise/react-native-sdk'
+
+export default function App() {
+  return (
+    <OctoProvider>
+      <RestOfYourApp />
+    </OctoProvider>
+  )
+}
+```
+
+### 2. Llamá `init()` después del login
+
+```tsx
+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).
+
+```tsx
+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](https://github.com/maurogallardo-cell/octovise-react-native-sdk/issues).
+
+Para temas del producto Octovise (configurar campañas, dudas de billing, etc.): [Backoffice → Soporte](https://backoffice.octovise.com.ar).
+
+## License
+
+[MIT](LICENSE) © 2026 Octovise Argentina S.A.S.

package/android/src/main/java/com/octovise/sdk/OctoFirebaseMessagingService.kt

@@ -0,0 +1,72 @@
+/**
+ * Firebase messaging service that intercepts data-only messages from Octovise.
+ * Builds custom notifications and tracks "received" events.
+ *
+ * Non-Octovise messages are ignored (the client's own service handles them).
+ * This service runs even when the app is killed — it's a native Android service.
+ */
+
+package com.octovise.sdk
+
+import com.google.firebase.messaging.FirebaseMessagingService
+import com.google.firebase.messaging.RemoteMessage
+import java.net.HttpURLConnection
+import java.net.URL
+import org.json.JSONObject
+
+class OctoFirebaseMessagingService : FirebaseMessagingService() {
+
+    override fun onMessageReceived(remoteMessage: RemoteMessage) {
+        val data = remoteMessage.data
+        if (data["source"] != "octovise") {
+            // Not ours — let the default handler or client's service deal with it
+            super.onMessageReceived(remoteMessage)
+            return
+        }
+
+        // Build and show the custom notification
+        val builder = OctoPushNotificationBuilder(applicationContext)
+        builder.build(data)
+
+        // Track "received" event (fire-and-forget, runs on background thread)
+        trackReceived(data)
+    }
+
+    private fun trackReceived(data: Map<String, String>) {
+        Thread {
+            try {
+                // Read base URL and API key from SharedPreferences (set by RN init())
+                val prefs = applicationContext.getSharedPreferences("octovise_sdk", MODE_PRIVATE)
+                val baseUrl = prefs.getString("base_url", null) ?: return@Thread
+                val apiKey = prefs.getString("api_key", null) ?: return@Thread
+                val userId = prefs.getString("user_id", null) ?: return@Thread
+
+                val sendId = data["send_id"] ?: return@Thread
+
+                val payload = JSONObject().apply {
+                    put("user_id", userId)
+                    put("send_id", sendId.toIntOrNull() ?: 0)
+                    put("event", "received")
+                    put("meta", JSONObject().apply {
+                        put("device", "mobile")
+                        put("platform", "android")
+                    })
+                }
+
+                val url = URL("$baseUrl/event")
+                val conn = url.openConnection() as HttpURLConnection
+                conn.requestMethod = "POST"
+                conn.setRequestProperty("Content-Type", "application/json")
+                conn.setRequestProperty("X-API-Key", apiKey)
+                conn.connectTimeout = 5000
+                conn.readTimeout = 5000
+                conn.doOutput = true
+                conn.outputStream.write(payload.toString().toByteArray())
+                conn.responseCode // trigger the request
+                conn.disconnect()
+            } catch (_: Exception) {
+                // Fire-and-forget — if tracking fails, the notification still shows
+            }
+        }.start()
+    }
+}

package/android/src/main/java/com/octovise/sdk/OctoPushDismissReceiver.kt

@@ -0,0 +1,54 @@
+/**
+ * Broadcast receiver that fires when the user swipes away an Octovise notification.
+ * Tracks "dismiss" event via the SDK API.
+ */
+
+package com.octovise.sdk
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import java.net.HttpURLConnection
+import java.net.URL
+import org.json.JSONObject
+
+class OctoPushDismissReceiver : BroadcastReceiver() {
+
+    override fun onReceive(context: Context, intent: Intent) {
+        val sendId = intent.getStringExtra("octovise_send_id") ?: return
+
+        Thread {
+            try {
+                val prefs = context.getSharedPreferences("octovise_sdk", Context.MODE_PRIVATE)
+                val baseUrl = prefs.getString("base_url", null) ?: return@Thread
+                val apiKey = prefs.getString("api_key", null) ?: return@Thread
+                val userId = prefs.getString("user_id", null) ?: return@Thread
+
+                val payload = JSONObject().apply {
+                    put("user_id", userId)
+                    put("send_id", sendId.toIntOrNull() ?: 0)
+                    put("event", "dismiss")
+                    put("meta", JSONObject().apply {
+                        put("device", "mobile")
+                        put("platform", "android")
+                        put("close_method", "swipe")
+                    })
+                }
+
+                val url = URL("$baseUrl/event")
+                val conn = url.openConnection() as HttpURLConnection
+                conn.requestMethod = "POST"
+                conn.setRequestProperty("Content-Type", "application/json")
+                conn.setRequestProperty("X-API-Key", apiKey)
+                conn.connectTimeout = 5000
+                conn.readTimeout = 5000
+                conn.doOutput = true
+                conn.outputStream.write(payload.toString().toByteArray())
+                conn.responseCode
+                conn.disconnect()
+            } catch (_: Exception) {
+                // Fire-and-forget
+            }
+        }.start()
+    }
+}

package/android/src/main/java/com/octovise/sdk/OctoPushModule.kt

@@ -0,0 +1,26 @@
+/**
+ * React Native bridge module for Android.
+ * Persists SDK config (apiKey, userId, baseUrl) to SharedPreferences
+ * so the native FirebaseMessagingService can access them when JS isn't running.
+ */
+
+package com.octovise.sdk
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+
+class OctoPushModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String = "OctoPushModule"
+
+    @ReactMethod
+    fun configure(apiKey: String, userId: String, baseUrl: String) {
+        val prefs = reactApplicationContext.getSharedPreferences("octovise_sdk", 0)
+        prefs.edit()
+            .putString("api_key", apiKey)
+            .putString("user_id", userId)
+            .putString("base_url", baseUrl)
+            .apply()
+    }
+}

package/android/src/main/java/com/octovise/sdk/OctoPushNotificationBuilder.kt

@@ -0,0 +1,142 @@
+/**
+ * Builds custom notifications for Octovise data-only push messages.
+ * Supports two layouts: inline (thumbnail) and hero (BigPictureStyle).
+ *
+ * Called by FirebaseMessagingService when a data message with
+ * source=octovise arrives — regardless of app state (foreground/background/killed).
+ */
+
+package com.octovise.sdk
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.os.Build
+import androidx.core.app.NotificationCompat
+import java.net.URL
+
+class OctoPushNotificationBuilder(private val context: Context) {
+
+    companion object {
+        private const val CHANNEL_ID_DEFAULT = "octovise_marketing"
+        private const val CHANNEL_NAME = "Octovise"
+    }
+
+    fun build(data: Map<String, String>) {
+        val title = data["title"] ?: return
+        val body = data["body"] ?: return
+        val sendId = data["send_id"] ?: "0"
+        val imageUrl = data["image_url"]
+        val imageLayout = data["image_layout"] ?: "hero"
+        val deepLink = data["deep_link"]
+        val channelId = data["channel_id"] ?: CHANNEL_ID_DEFAULT
+        val collapseKey = data["collapse_key"]
+        val campaignId = data["campaign_id"] ?: "0"
+
+        ensureChannel(channelId)
+
+        // Download image (if present) on the background thread
+        val imageBitmap = imageUrl?.let { downloadImage(it) }
+
+        // Build tap intent — launches the app's main activity with deep link as extra
+        val launchIntent = context.packageManager.getLaunchIntentForPackage(context.packageName)?.apply {
+            addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+            putExtra("octovise_send_id", sendId)
+            putExtra("octovise_deep_link", deepLink ?: "")
+            putExtra("octovise_source", "octovise")
+        }
+
+        val pendingIntent = PendingIntent.getActivity(
+            context,
+            sendId.hashCode(),
+            launchIntent,
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+        )
+
+        // Build dismiss intent for tracking
+        val dismissIntent = Intent(context, OctoPushDismissReceiver::class.java).apply {
+            putExtra("octovise_send_id", sendId)
+        }
+        val dismissPendingIntent = PendingIntent.getBroadcast(
+            context,
+            sendId.hashCode() + 1,
+            dismissIntent,
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+        )
+
+        val builder = NotificationCompat.Builder(context, channelId)
+            .setSmallIcon(getSmallIcon())
+            .setContentTitle(title)
+            .setContentText(body)
+            .setAutoCancel(true)
+            .setContentIntent(pendingIntent)
+            .setDeleteIntent(dismissPendingIntent)
+            .setPriority(NotificationCompat.PRIORITY_HIGH)
+
+        if (collapseKey != null) {
+            builder.setGroup(collapseKey)
+        }
+
+        // Apply image layout
+        if (imageBitmap != null) {
+            when (imageLayout) {
+                "inline" -> {
+                    // Thumbnail to the right of title/body
+                    builder.setLargeIcon(imageBitmap)
+                }
+                "hero" -> {
+                    // Large image below text (always expanded)
+                    builder.setStyle(
+                        NotificationCompat.BigPictureStyle()
+                            .bigPicture(imageBitmap)
+                            .bigLargeIcon(null as Bitmap?)
+                    )
+                    builder.setLargeIcon(imageBitmap)
+                }
+            }
+        }
+
+        val notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        notificationManager.notify(sendId.hashCode(), builder.build())
+    }
+
+    private fun ensureChannel(channelId: String) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+            if (manager.getNotificationChannel(channelId) == null) {
+                val channel = NotificationChannel(
+                    channelId,
+                    CHANNEL_NAME,
+                    NotificationManager.IMPORTANCE_HIGH,
+                ).apply {
+                    description = "Octovise marketing notifications"
+                    enableVibration(true)
+                }
+                manager.createNotificationChannel(channel)
+            }
+        }
+    }
+
+    private fun downloadImage(url: String): Bitmap? {
+        return try {
+            val connection = URL(url).openConnection()
+            connection.connectTimeout = 5000
+            connection.readTimeout = 5000
+            BitmapFactory.decodeStream(connection.getInputStream())
+        } catch (e: Exception) {
+            null
+        }
+    }
+
+    private fun getSmallIcon(): Int {
+        // Try the app's notification icon, fall back to app icon
+        val resId = context.resources.getIdentifier(
+            "ic_notification", "drawable", context.packageName,
+        )
+        return if (resId != 0) resId else context.applicationInfo.icon
+    }
+}

package/dist/api.d.ts

@@ -0,0 +1,38 @@
+import type { InAppMessage, EventType, EventMeta } from './types';
+export declare const DEFAULT_BASE_URL = "https://sdk-api.octovise.com.ar";
+export declare function configure(key: string, userId: number | string, userHash?: string, url?: string, appVer?: string): void;
+export declare function buildTelemetryContext(): Record<string, string>;
+export declare function check(sendId?: number): Promise<InAppMessage | null>;
+export interface RuleEntry {
+    id: string;
+    send_id: number;
+    target_screens: number[] | null;
+    content: InAppMessage;
+}
+export interface RulesResponse {
+    rules: RuleEntry[];
+    routes: Array<Record<string, unknown>>;
+}
+export declare function fetchRules(): Promise<RulesResponse | null>;
+export interface ScreenViewWire {
+    screen_id: number;
+    entity_type: string | null;
+    entity_id: number | null;
+    reference: string | null;
+    session_id: string;
+    ts: string;
+}
+export declare function trackScreenViews(views: ScreenViewWire[]): Promise<boolean>;
+export declare function setEventObserver(cb?: (event: EventType, meta: Partial<EventMeta>, sendId: number) => void): void;
+export declare function trackEvent(sendId: number, event: EventType, meta: Partial<EventMeta>): void;
+export interface TelemetryEvent {
+    kind: 'error' | 'metric';
+    name: string;
+    value?: number;
+    meta?: Record<string, unknown>;
+}
+export declare function sendTelemetry(events: TelemetryEvent[]): void;
+export declare function testInApp(): Promise<boolean>;
+export declare function registerDevice(fcmToken: string): Promise<void>;
+export declare function getUserId(): string;
+export declare function getBaseUrl(): string;