> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK de React Native

> Captura calificaciones woku y NPS (texto y audio) desde tu app React Native, con buffer offline y entrega consciente de cuarentenas

<Info>
  **Disponible en el plan Corporate.** Esta funcionalidad forma parte de las capacidades empresariales de woku. [Conversa con nuestro equipo comercial](https://woku.app/pricing).
</Info>

El SDK **`@wokuapp/react-native`** permite capturar feedback desde tu app
móvil: calificaciones **woku** (1 a 5) y **NPS** (0 a 10), con comentario
de texto o audio. Incluye **buffer offline** (las capturas se encolan y se
reintentan cuando hay conexión) y respeta las reglas de **cuarentena** de
la empresa.

<Note>
  Además de la captura nativa, el SDK también permite **compartir o incrustar
  el [widget web de woku](/integraciones/widget-js)** dentro de tu app (por
  ejemplo, en una vista WebView), reutilizando la misma experiencia de
  captura woku/NPS en canales híbridos.
</Note>

## Instalación

```bash theme={null}
npm install @wokuapp/react-native
```

`react` y `react-native` son peer dependencies (ya presentes en tu app).

## Inicialización

Crea una instancia de `WokuSdk` una sola vez y reutilízala. Pasa un
adaptador de **almacenamiento** para que la cola offline persista entre
sesiones (AsyncStorage o MMKV sirven directamente).

```ts theme={null}
import AsyncStorage from '@react-native-async-storage/async-storage';
import { WokuSdk } from '@wokuapp/react-native';

export const woku = new WokuSdk({
  apiUrl: 'https://clientapi.woku.app',
  companyId: 'tu_company_id',
  publicKey: 'tu_public_key', // clave pública de captura por empresa
  storage: AsyncStorage,       // persiste la cola offline
});
```

| Opción             | Requerida   | Descripción                                     |
| ------------------ | ----------- | ----------------------------------------------- |
| `apiUrl`           | sí          | URL base de la API de woku.                     |
| `companyId`        | sí          | Empresa a la que pertenecen las capturas.       |
| `publicKey`        | sí          | Clave pública de captura emitida por empresa.   |
| `storage`          | recomendada | Adaptador de persistencia para la cola offline. |
| `http`             | no          | Transporte HTTP; por defecto usa `fetch`.       |
| `logger`           | no          | Logger opcional.                                |
| `maxQueueAttempts` | no          | Descarta una captura tras N intentos fallidos.  |

## Capturar una calificación woku

```ts theme={null}
const result = await woku.captureWoku({
  wokuId: 'woku_123',
  rating: 5, // entero 1..5
  comment: 'Excelente atención',
  respondent: { email: 'ana@example.com' }, // opcional
});
```

## Capturar un NPS

```ts theme={null}
await woku.captureNps({
  npsId: 'nps_1',
  score: 9, // entero 0..10
  comment: 'Lo recomendaría',
});
```

### Comentario de audio

Ambas capturas aceptan un adjunto de audio en lugar (o además) del texto:

```ts theme={null}
await woku.captureWoku({
  wokuId: 'woku_123',
  rating: 4,
  audio: { uri: 'file:///path/grabacion.m4a', mimeType: 'audio/m4a' },
});
```

### Identificar al respondente

El feedback es **anónimo** salvo que envíes un identificador. Cualquiera de
estos campos es opcional:

```ts theme={null}
respondent: {
  email: 'ana@example.com',
  phone: '+56911111111',
  externalId: 'crm_4821', // id externo que controla tu app
}
```

## Resultado de una captura

Cada captura devuelve un `SubmissionResult` con su estado:

| `status`      | Significado                                          |
| ------------- | ---------------------------------------------------- |
| `sent`        | Entregada al servidor.                               |
| `queued`      | Sin conexión: quedó en la cola para reintentar.      |
| `quarantined` | Bloqueada por una regla de cuarentena de la empresa. |
| `failed`      | Falló y se descartó tras agotar los intentos.        |

## Modo offline

Las capturas que no se pueden enviar se **encolan** automáticamente y se
reintentan. Puedes forzar el envío y consultar la cola:

```ts theme={null}
await woku.flush();           // intenta enviar todo lo pendiente
const pending = await woku.pendingCount();
await woku.clearQueue();      // descarta la cola (con cuidado)
```

Un buen momento para llamar `flush()` es cuando la app vuelve a primer
plano o cuando recuperas conectividad.

## Manejo de errores

El SDK expone clases de error tipadas para distinguir las causas:

```ts theme={null}
import {
  WokuConfigError,
  WokuValidationError,
  WokuQuarantineError,
  WokuNetworkError,
} from '@wokuapp/react-native';
```

* `WokuValidationError`, datos inválidos (p. ej. `rating` fuera de 1..5).
* `WokuQuarantineError`, la captura fue bloqueada por cuarentena.
* `WokuNetworkError`, fallo de red (la captura suele quedar encolada).
* `WokuConfigError`, configuración incompleta al inicializar.

## Plataformas

<Note>
  El SDK **`@wokuapp/react-native`** integra el feedback de woku en apps móviles
  y **funciona tanto en Android como en iOS**. React Native expone una única API
  en JavaScript/TypeScript y hace el puente a las capacidades nativas de cada
  plataforma, de modo que el mismo código corre en ambas.
</Note>

| Plataforma  | Soporte  | Mínimo               |
| ----------- | -------- | -------------------- |
| **Android** | Completo | API 24 (Android 7.0) |
| **iOS**     | Completo | iOS 13               |

La grabación de audio para comentarios usa el módulo nativo correspondiente en
cada plataforma; el resto de la API es idéntico en Android e iOS.

## Versionado

El SDK sigue **versionado semántico** (`MAJOR.MINOR.PATCH`):

* **MAJOR**, cambios incompatibles en la API pública del SDK.
* **MINOR**, funcionalidades nuevas compatibles hacia atrás.
* **PATCH**, correcciones de errores compatibles hacia atrás.

Las versiones publicadas y sus notas están disponibles en línea en el
[paquete npm](https://www.npmjs.com/package/@wokuapp/react-native) y en los
[releases de GitHub](https://github.com/wokuApp/sdks/releases). Te
recomendamos fijar un rango compatible (por ejemplo `^1.4.0`) y revisar el
changelog antes de subir de versión MAJOR.

## Changelog

Las entradas más recientes primero. La versión publicada cubre por igual
**Android e iOS**.

### 1.4.0 a 2026-05-12

* Soporte de comentarios de audio en NPS además de woku.
* Nuevo campo `respondent.externalId` para correlacionar con sistemas propios.

### 1.3.1 a 2026-03-28

* Corrección: la cola offline ya no reintenta capturas en `quarantined`.
* Mejora en los reintentos con `maxQueueAttempts`.

### 1.3.0 a 2026-02-10

* Buffer offline persistente configurable vía adaptador `storage`.
* Errores tipados: `WokuConfigError`, `WokuValidationError`,
  `WokuQuarantineError`, `WokuNetworkError`.

### 1.2.0 a 2025-12-15

* Soporte de iOS 13+ y Android API 24+.
* Método `flush()` para forzar el envío de la cola pendiente.

## Recursos

* **Paquete npm:** [@wokuapp/react-native](https://www.npmjs.com/package/@wokuapp/react-native)
* **Código y ejemplos:** [github.com/wokuApp/sdks](https://github.com/wokuApp/sdks)
* **Releases y changelog:** [github.com/wokuApp/sdks/releases](https://github.com/wokuApp/sdks/releases)