npm package: @media-suite/reactnative-sdk
Description: MediaSuite Native SDK — React Native SDK for rendering and tracking ads in mobile apps. IAB/MRC viewability standards, impression/click tracking, and ad rotation.
Latest version: 0.3.0

# @media-suite/reactnative-sdk

React Native SDK for MediaSuite ad platform. Renders ads, tracks impressions/clicks with IAB/MRC viewability compliance.

## Installation

```bash
npm install @media-suite/reactnative-sdk @react-native-async-storage/async-storage
```

## Quick Start

### 1. Wrap your app with the Provider

```tsx
import { MediaSuiteProvider } from '@media-suite/reactnative-sdk';

export default function App() {
  return (
    <MediaSuiteProvider
      config={{
        companyId: '507f1f77bcf86cd799439011',
        apiKey: 'your-public-embed-key',
        baseUrl: 'https://api.mediasuite.com', // optional
      }}
    >
      <MyApp />
    </MediaSuiteProvider>
  );
}
```

> **Security:** The `apiKey` must be a restricted public embed key with read-only SDK permissions. Never use admin or secret keys in client-side code.

### 2. Render ads anywhere

```tsx
import { MediaSuiteAd } from '@media-suite/reactnative-sdk';

function HomeScreen() {
  return (
    <View>
      <Text>My App</Text>

      <MediaSuiteAd
        spaceCode="banner-home-principal"
        screenName="HomeScreen"
        style={{ height: 90, marginVertical: 16 }}
      />

      <MediaSuiteAd
        spaceCode="sidebar-top"
        screenName="HomeScreen"
        style={{ height: 250 }}
        onAdLoaded={(space) => console.log('Ads loaded:', space.ads.length)}
        onError={(err) => console.warn('Ad error:', err)}
      />
    </View>
  );
}
```

## MediaSuiteAd Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `spaceCode` | `string` | Yes | Ad space code from MediaSuite panel |
| `screenName` | `string` | No | Screen name for referrer analytics (e.g. `'HomeScreen'`) |
| `style` | `ViewStyle` | No | Container styles |
| `onAdLoaded` | `(space) => void` | No | Callback when ads are loaded |
| `onError` | `(error) => void` | No | Callback on error |

## Features

- **IAB/MRC Viewability** — 50% visible for 1 continuous second before counting impression
- **Ad Rotation** — Automatic rotation when space has multiple ads
- **Impression Tracking** — Debounced, deduplicated, viewability-gated, with retry on network failure
- **Click Tracking** — Fire-and-forget tracking + deep link to destination
- **Visitor Persistence** — Crypto-secure UUID stored in AsyncStorage across sessions
- **Background Handling** — Pauses tracking when app goes to background
- **Reactive Device Detection** — Updates on orientation and window size changes

## Requirements

- React Native >= 0.72
- React >= 18
- @react-native-async-storage/async-storage >= 1.19

## Building

```bash
npm run build    # Compiles TypeScript to dist/
```

The package ships compiled JS + type declarations via the `dist/` directory.

## Architecture

```
MediaSuiteProvider (Context)
  ├── Manages config, visitor ID, device detection
  ├── Caches ad space responses
  ├── Retry logic for failed impression tracking
  └── Provides: fetchSpace, trackImpression, getClickUrl

MediaSuiteAd (Component)
  ├── Fetches ads for a space code
  ├── Renders Image with touch handling
  ├── IAB viewability: measureInWindow + 200ms polling
  ├── Passes screenName as page_url for referrer metrics
  └── Auto-rotates ads on configurable interval
```

## API Endpoints Used

| Endpoint | Purpose |
|----------|---------|
| `GET /sdk/serve/:companyId` | Fetch ads for spaces |
| `GET /sdk/impressions` | Register viewable impression |
| `GET /sdk/click/:placementId` | Track click + redirect |