@media-suite/reactnative-sdk

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

Installation

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

Quick Start

1. Wrap your app with the Provider

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

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

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 |