@media-suite/reactnative-sdk 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @mediasuite/react-native-sdk
+
+React Native SDK for MediaSuite ad platform. Renders ads, tracks impressions/clicks with IAB/MRC viewability compliance.
+
+## Installation
+
+```bash
+npm install @mediasuite/react-native-sdk @react-native-async-storage/async-storage
+```
+
+## Quick Start
+
+### 1. Wrap your app with the Provider
+
+```tsx
+import { MediaSuiteProvider } from '@mediasuite/react-native-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 '@mediasuite/react-native-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 |

package/dist/MediaSuiteAd.d.ts

@@ -0,0 +1,12 @@
+import { type ViewStyle } from 'react-native';
+import type { AdSpace } from './types';
+interface Props {
+    spaceCode: string;
+    style?: ViewStyle;
+    /** Screen name for analytics (e.g. 'HomeScreen'). Sent as page_url for referrer metrics. */
+    screenName?: string;
+    onAdLoaded?: (space: AdSpace) => void;
+    onError?: (error: string) => void;
+}
+export declare function MediaSuiteAd({ spaceCode, style, screenName, onAdLoaded, onError }: Props): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/MediaSuiteAd.js

@@ -0,0 +1,159 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState, useRef, useCallback } from 'react';
+import { View, Image, TouchableOpacity, Linking, StyleSheet, Dimensions, AppState, } from 'react-native';
+import { useMediaSuite } from './MediaSuiteProvider';
+export function MediaSuiteAd({ spaceCode, style, screenName, onAdLoaded, onError }) {
+    const { fetchSpace, trackImpression, getClickUrl, visitorId } = useMediaSuite();
+    const [ads, setAds] = useState([]);
+    const [index, setIndex] = useState(0);
+    const [loaded, setLoaded] = useState(false);
+    const rotationMs = useRef(5000);
+    const impressionTracked = useRef(false);
+    const viewRef = useRef(null);
+    const viewabilityTimer = useRef(null);
+    const scrollCheckInterval = useRef(null);
+    const adsRef = useRef([]);
+    const consecutiveFailures = useRef(0);
+    // Keep adsRef in sync for use inside interval callbacks
+    useEffect(() => { adsRef.current = ads; }, [ads]);
+    // Fetch ads — skip until visitorId is ready to avoid false onError
+    useEffect(() => {
+        if (!visitorId)
+            return;
+        let cancelled = false;
+        (async () => {
+            const space = await fetchSpace(spaceCode);
+            if (cancelled)
+                return;
+            if (!space || !space.ads.length) {
+                onError?.('No ads for space: ' + spaceCode);
+                return;
+            }
+            rotationMs.current = (space.rotation_seconds || 5) * 1000;
+            setAds(space.ads);
+            consecutiveFailures.current = 0;
+            onAdLoaded?.(space);
+        })();
+        return () => { cancelled = true; };
+    }, [spaceCode, fetchSpace, visitorId, onAdLoaded, onError]);
+    // IAB viewability: 50% visible for 1 continuous second
+    const cancelViewabilityCheck = useCallback(() => {
+        if (viewabilityTimer.current) {
+            clearTimeout(viewabilityTimer.current);
+            viewabilityTimer.current = null;
+        }
+    }, []);
+    // Rotation — uses adsRef to avoid stale closures
+    useEffect(() => {
+        if (ads.length <= 1)
+            return;
+        const timer = setInterval(() => {
+            setIndex((prev) => (prev + 1) % adsRef.current.length);
+            setLoaded(false);
+            impressionTracked.current = false;
+            cancelViewabilityCheck();
+        }, rotationMs.current);
+        return () => clearInterval(timer);
+    }, [ads.length, cancelViewabilityCheck]);
+    const checkViewability = useCallback(() => {
+        // Snapshot the current ad before async measurement
+        const currentAd = ads[index];
+        if (impressionTracked.current || !viewRef.current || !currentAd)
+            return;
+        viewRef.current.measureInWindow((x, y, width, height) => {
+            if (!width || !height)
+                return;
+            const screen = Dimensions.get('window');
+            const visibleTop = Math.max(0, y);
+            const visibleBottom = Math.min(screen.height, y + height);
+            const visibleLeft = Math.max(0, x);
+            const visibleRight = Math.min(screen.width, x + width);
+            const visibleHeight = Math.max(0, visibleBottom - visibleTop);
+            const visibleWidth = Math.max(0, visibleRight - visibleLeft);
+            const visibleArea = visibleWidth * visibleHeight;
+            const totalArea = width * height;
+            const visibleRatio = totalArea > 0 ? visibleArea / totalArea : 0;
+            if (visibleRatio >= 0.5) {
+                // 50% visible — start 1s timer if not already running
+                if (!viewabilityTimer.current) {
+                    viewabilityTimer.current = setTimeout(() => {
+                        if (!impressionTracked.current) {
+                            impressionTracked.current = true;
+                            trackImpression(currentAd.placement_id, screenName);
+                        }
+                    }, 1000);
+                }
+            }
+            else {
+                // Less than 50% visible — cancel timer
+                cancelViewabilityCheck();
+            }
+        });
+    }, [ads, index, trackImpression, cancelViewabilityCheck, screenName]);
+    // Poll viewability every 200ms while image is loaded
+    useEffect(() => {
+        if (!loaded || !ads.length)
+            return;
+        checkViewability();
+        scrollCheckInterval.current = setInterval(checkViewability, 200);
+        return () => {
+            if (scrollCheckInterval.current)
+                clearInterval(scrollCheckInterval.current);
+            cancelViewabilityCheck();
+        };
+    }, [loaded, ads.length, checkViewability, cancelViewabilityCheck]);
+    // Pause when app goes to background
+    useEffect(() => {
+        const sub = AppState.addEventListener('change', (state) => {
+            if (state !== 'active') {
+                cancelViewabilityCheck();
+            }
+            else if (loaded && !impressionTracked.current) {
+                checkViewability();
+            }
+        });
+        return () => sub.remove();
+    }, [loaded, checkViewability, cancelViewabilityCheck]);
+    // Image failure — advance to next ad if available, prevent infinite loop
+    const handleImageError = useCallback(() => {
+        onError?.('Image failed: ' + ads[index]?.image_url);
+        consecutiveFailures.current++;
+        if (consecutiveFailures.current < ads.length && ads.length > 1) {
+            setIndex((prev) => (prev + 1) % ads.length);
+            setLoaded(false);
+            impressionTracked.current = false;
+            cancelViewabilityCheck();
+        }
+    }, [ads, index, onError, cancelViewabilityCheck]);
+    // Click handler — fire-and-forget tracking + open destination URL
+    const handlePress = useCallback(async () => {
+        const ad = ads[index];
+        if (!ad)
+            return;
+        const clickUrl = getClickUrl(ad.placement_id, screenName);
+        // Fire tracking call (don't wait for response)
+        fetch(clickUrl).catch(() => { });
+        // Open the destination URL directly
+        if (ad.click_url) {
+            await Linking.openURL(ad.click_url).catch(() => { });
+        }
+    }, [ads, index, getClickUrl, screenName]);
+    if (!ads.length)
+        return null;
+    const ad = ads[index];
+    return (_jsx(TouchableOpacity, { activeOpacity: 0.9, onPress: handlePress, style: [styles.container, style], accessibilityLabel: ad.alt_text || 'Advertisement', accessibilityRole: "link", children: _jsx(View, { ref: viewRef, collapsable: false, children: _jsx(Image, { source: { uri: ad.image_url }, style: [styles.image, loaded && styles.imageLoaded], resizeMode: "contain", onLoad: () => { setLoaded(true); consecutiveFailures.current = 0; }, onError: handleImageError }, ad.placement_id) }) }));
+}
+const styles = StyleSheet.create({
+    container: {
+        overflow: 'hidden',
+        backgroundColor: 'transparent',
+    },
+    image: {
+        width: '100%',
+        aspectRatio: 16 / 9,
+        opacity: 0,
+    },
+    imageLoaded: {
+        opacity: 1,
+    },
+});

package/dist/MediaSuiteProvider.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import type { MediaSuiteConfig, AdSpace } from './types';
+interface ContextValue {
+    config: MediaSuiteConfig;
+    visitorId: string;
+    device: 'web' | 'mobile';
+    fetchSpace: (spaceCode: string) => Promise<AdSpace | null>;
+    trackImpression: (placementId: string, screenName?: string) => void;
+    getClickUrl: (placementId: string, screenName?: string) => string;
+}
+export declare const useMediaSuite: () => ContextValue;
+export declare function MediaSuiteProvider({ config, children, }: {
+    config: MediaSuiteConfig;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/MediaSuiteProvider.js

@@ -0,0 +1,126 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useState, useRef, useCallback } from 'react';
+import { useWindowDimensions } from 'react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+function uuid() {
+    // Prefer crypto.randomUUID (available since RN 0.73+ with Hermes)
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // Fallback: crypto.getRandomValues
+    if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+        const buf = new Uint8Array(16);
+        crypto.getRandomValues(buf);
+        buf[6] = (buf[6] & 0x0f) | 0x40; // version 4
+        buf[8] = (buf[8] & 0x3f) | 0x80; // variant 1
+        const hex = Array.from(buf, (b) => b.toString(16).padStart(2, '0')).join('');
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+    // Last resort: Math.random
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+const Ctx = createContext(null);
+export const useMediaSuite = () => {
+    const ctx = useContext(Ctx);
+    if (!ctx)
+        throw new Error('Wrap your app with <MediaSuiteProvider>');
+    return ctx;
+};
+const MAX_RETRIES = 2;
+const RETRY_DELAY = 3000;
+export function MediaSuiteProvider({ config, children, }) {
+    const baseUrl = (config.baseUrl || 'https://api.mediasuite.com').replace(/\/$/, '');
+    const [visitorId, setVisitorId] = useState('');
+    const sentImpressions = useRef(new Set());
+    const pendingImpressions = useRef([]);
+    const debounceTimer = useRef(null);
+    const cache = useRef({});
+    const retryTimer = useRef(null);
+    const isMounted = useRef(true);
+    const flushImpressionsRef = useRef(null);
+    // Reactive device detection — updates on orientation/window changes
+    const { width } = useWindowDimensions();
+    const device = width <= 768 ? 'mobile' : 'web';
+    // Restore or create visitor_id
+    useEffect(() => {
+        (async () => {
+            let vid = await AsyncStorage.getItem('_ms_vid');
+            if (!vid) {
+                vid = uuid();
+                await AsyncStorage.setItem('_ms_vid', vid);
+            }
+            setVisitorId(vid);
+        })();
+    }, []);
+    // Cleanup all timers on unmount
+    useEffect(() => {
+        return () => {
+            isMounted.current = false;
+            if (debounceTimer.current)
+                clearTimeout(debounceTimer.current);
+            if (retryTimer.current)
+                clearTimeout(retryTimer.current);
+        };
+    }, []);
+    const fetchSpace = useCallback(async (spaceCode) => {
+        const cacheKey = `${spaceCode}:${device}`;
+        if (cache.current[cacheKey])
+            return cache.current[cacheKey];
+        if (!visitorId)
+            return null;
+        try {
+            const url = `${baseUrl}/sdk/serve/${encodeURIComponent(config.companyId)}?spaces=${encodeURIComponent(spaceCode)}&device=${device}&visitor_id=${encodeURIComponent(visitorId)}`;
+            const res = await fetch(url, {
+                headers: { 'api-key': config.apiKey },
+            });
+            if (!res.ok)
+                return null;
+            const json = await res.json();
+            const space = json.data.spaces.find((s) => s.space_code === spaceCode) || null;
+            if (space)
+                cache.current[cacheKey] = space;
+            return space;
+        }
+        catch {
+            return null;
+        }
+    }, [baseUrl, config.companyId, config.apiKey, device, visitorId]);
+    const flushImpressions = useCallback((screenName, retryCount = 0) => {
+        if (!visitorId || !isMounted.current)
+            return;
+        const ids = [...pendingImpressions.current];
+        if (!ids.length)
+            return;
+        pendingImpressions.current = [];
+        const pageUrl = encodeURIComponent(screenName || 'app://unknown');
+        const url = `${baseUrl}/sdk/impressions?company=${encodeURIComponent(config.companyId)}&placements=${ids.join(',')}&visitor_id=${encodeURIComponent(visitorId)}&device=${device}&page_url=${pageUrl}`;
+        fetch(url, { headers: { 'api-key': config.apiKey } }).catch(() => {
+            if (retryCount < MAX_RETRIES && isMounted.current) {
+                ids.forEach((id) => sentImpressions.current.delete(id));
+                pendingImpressions.current.push(...ids);
+                if (retryTimer.current)
+                    clearTimeout(retryTimer.current);
+                retryTimer.current = setTimeout(() => flushImpressionsRef.current?.(screenName, retryCount + 1), RETRY_DELAY);
+            }
+        });
+    }, [baseUrl, config.companyId, config.apiKey, device, visitorId]);
+    useEffect(() => { flushImpressionsRef.current = flushImpressions; }, [flushImpressions]);
+    const trackImpression = useCallback((placementId, screenName) => {
+        if (sentImpressions.current.has(placementId))
+            return;
+        sentImpressions.current.add(placementId);
+        pendingImpressions.current.push(placementId);
+        if (debounceTimer.current)
+            clearTimeout(debounceTimer.current);
+        debounceTimer.current = setTimeout(() => flushImpressions(screenName), 1000);
+    }, [flushImpressions]);
+    const getClickUrl = useCallback((placementId, screenName) => {
+        const pageUrl = encodeURIComponent(screenName || 'app://unknown');
+        return `${baseUrl}/sdk/click/${encodeURIComponent(placementId)}?vid=${encodeURIComponent(visitorId)}&device=${device}&page_url=${pageUrl}`;
+    }, [baseUrl, visitorId, device]);
+    // Render children always — ad components handle the "not ready" state
+    return (_jsx(Ctx.Provider, { value: { config, visitorId, device, fetchSpace, trackImpression, getClickUrl }, children: children }));
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { MediaSuiteProvider } from './MediaSuiteProvider';
+export { MediaSuiteAd } from './MediaSuiteAd';
+export type { MediaSuiteConfig, AdSpace, Ad } from './types';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { MediaSuiteProvider } from './MediaSuiteProvider';
+export { MediaSuiteAd } from './MediaSuiteAd';

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+export interface MediaSuiteConfig {
+    /** MongoDB ObjectId of the company */
+    companyId: string;
+    /** Public embed API key (must be a restricted key with read-only SDK permissions) */
+    apiKey: string;
+    /** API base URL. Defaults to https://api.mediasuite.com */
+    baseUrl?: string;
+}
+export interface Ad {
+    placement_id: string;
+    image_url: string;
+    alt_text?: string;
+    click_url?: string;
+}
+export interface AdSpace {
+    space_code: string;
+    rotation_seconds: number;
+    ads: Ad[];
+}
+export interface ServeResponse {
+    success: boolean;
+    data: {
+        spaces: AdSpace[];
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@media-suite/reactnative-sdk",
+  "version": "0.1.0",
+  "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.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.19.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0"
+  },
+  "keywords": [
+    "mediasuite",
+    "ads",
+    "react-native",
+    "sdk",
+    "advertising",
+    "viewability",
+    "IAB"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist/"
+  ],
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-native": "^0.72.8",
+    "typescript": "^5.9.3"
+  }
+}