# SDK API reference

## JavaScript configuration

`createAnalyticsSdk(options)` accepts:

| Option | Required | Default | Contract |
| --- | --- | --- | --- |
| `endpoint` | yes | — | HTTPS URL; HTTP is allowed only for localhost |
| `writeKey` | yes | — | Non-empty string, at most 256 characters |
| `storage` | yes | — | Object with `getItem`, `setItem`, and `removeItem` |
| `batchSize` | no | `50` | Integer from 1 through 100 |
| `maxQueueSize` | no | `1000` | Positive integer |
| `flushIntervalMs` | no | `15000` | Positive integer milliseconds |
| `sessionTimeoutMs` | no | `1800000` | Positive integer milliseconds |
| `baseRetryMs` | no | `1000` | Positive integer milliseconds |
| `maxRetryMs` | no | `60000` | At least `baseRetryMs` |
| `requestTimeoutMs` | no | `15000` | Integer from 1 through 60000 |
| `propertyAllowlist` | no | canonical allowlist | Intersected with canonical keys |
| `propertyBlocklist` | no | empty | Additional keys to discard |
| `uuidFactory` | no | Web Crypto | Must return a UUIDv4 |
| `fetchImplementation` | no | global `fetch` | Fetch-compatible function |

Platform entry points:

- `@dozz-affiliate/analytics-sdk/browser` exports `createAnalyticsSdk` and
  `createWebStorageAdapter`.
- `@dozz-affiliate/analytics-sdk/react-native` exports `createAnalyticsSdk` and
  `createAsyncStorageAdapter`.
- The root package exports `createAnalyticsSdk`, `PROPERTY_ALLOWLIST`, and
  `PII_BLOCKLIST`.

### JavaScript methods

| Method | Result |
| --- | --- |
| `initialize(initialUrl = null)` | Restores state, optionally captures attribution, and returns the SDK instance |
| `setConsent('unknown' | 'granted' | 'denied')` | Persists and applies consent |
| `getConsent()` | Current consent string |
| `captureAttribution(url)` | Captured attribution object or `null` |
| `trackEvent(name, properties = {})` | Event UUID or `null` without consent |
| `trackScreen(name, properties = {})` | Event UUID or `null` |
| `trackTap(target, properties = {})` | Event UUID or `null` |
| `trackRide(action, properties = {})` | Event UUID or `null` |
| `flush()` | `{ sent, outcome? }` |
| `getDiagnostics()` | `{ dropped_events, rejected_events }` |
| `stop()` | Stops the timer and aborts active delivery |
| `reset()` | Erases consent, attribution, queue, and anonymous identity |

`flush()` outcomes are `acknowledge`, `retry`, `reject`, or `consent_required`.
An empty ready queue returns `{ sent: 0 }` without an outcome.

## Flutter configuration

`DozzAnalyticsConfig` accepts:

| Field | Required | Default | Contract |
| --- | --- | --- | --- |
| `endpoint` | yes | — | HTTPS URI; localhost HTTP is allowed |
| `writeKey` | yes | — | 1–256 characters |
| `batchSize` | no | `50` | 1–100 |
| `maximumQueueSize` | no | `1000` | Positive integer |
| `flushInterval` | no | 15 seconds | Positive duration |
| `sessionTimeout` | no | 30 minutes | Positive duration |
| `baseRetry` | no | 1 second | Positive duration |
| `maximumRetry` | no | 1 minute | At least `baseRetry` |
| `requestTimeout` | no | 15 seconds | Positive and at most 60 seconds |
| `propertyAllowlist` | no | canonical allowlist | Intersected with canonical keys |
| `propertyBlocklist` | no | empty | Additional keys to discard |

Construct `DozzAnalyticsSdk` with a config, `DozzStorage`, and `DozzHttpClient`.
The package supplies `SharedPreferencesDozzStorage` and `HttpDozzClient`.

### Flutter methods

| Method | Result |
| --- | --- |
| `initialize({String? initialUrl})` | `Future<DozzAnalyticsSdk>` |
| `setConsent(DozzConsent)` | `Future<void>` |
| `consent` | Current `DozzConsent` |
| `captureAttribution(String)` | `Future<String?>` click ID |
| `trackEvent`, `trackScreen`, `trackTap`, `trackRide` | `Future<String?>` event UUID |
| `flush()` | `Future<int>` acknowledged event count |
| `getDiagnostics()` | `Map<String, int>` |
| `stop()` | Stops timer and active delivery |
| `reset()` | Erases consent, attribution, queue, and anonymous identity |

Invalid configuration throws `ArgumentError` or `RangeError`. Storage errors
propagate. Network failures and timeouts retain events for retry.