# AdTogether React Native SDK — LLM Integration Reference

**Version:** 0.1.26

**Package:** `@adtogether/react-native-sdk`
**Distribution:** NPM
**Targets:** React Native CLI apps, Expo apps (iOS + Android)

> **This is a SEPARATE package from the Web SDK.** Do NOT import from `@adtogether/web-sdk` in React Native code.

### Install

```bash
npm install @adtogether/react-native-sdk
# or
yarn add @adtogether/react-native-sdk
```

### Initialize

```typescript
import { AdTogether } from '@adtogether/react-native-sdk';

// Call once before rendering any ad components
AdTogether.initialize({ appId: 'YOUR_APP_ID' });
```

**`AdTogether.initialize()` accepts:**
```typescript
interface AdTogetherOptions {
  appId?: string;       // Your registered app ID (preferred)
  apiKey?: string;      // Alternative name for appId
  baseUrl?: string;     // Override API base URL (optional)
  bundleId?: string;    // Explicit bundle/package ID (optional, auto-detected — see below)
  allowSelfAds?: boolean; // Show own ads as fallback (default: true)
}
```

**Bundle ID auto-detection:** The SDK automatically tries to detect `bundleId` using (in order):
1. `expo-application` — works in Expo and bare RN with expo modules installed
2. `react-native-device-info` — popular community module
3. RN built-in `NativeModules.PlatformConstants` (Android only)

If none of these are available, a `console.warn` is emitted. For best results, either provide `bundleId` manually in `initialize()` or install one of the supported packages.

**Tracking metadata:** Impression/click tracking payloads include `platform` (from `Platform.OS`) and `environment: "development"|"production"` (based on `__DEV__`).

### Banner Ad

```tsx
import { AdTogetherBanner } from '@adtogether/react-native-sdk';
import { View, Text } from 'react-native';

function MyScreen() {
  return (
    <View style={{ flex: 1 }}>
      <Text>My App Content</Text>

      <AdTogetherBanner
        adUnitId="home_banner" // optional — any label for this placement
        showCloseButton={true}
        onAdLoaded={() => console.log('Banner loaded!')}
        onAdFailedToLoad={(error) => console.error('Banner error:', error)}
        onAdClosed={() => console.log('User closed the ad')}
      />
    </View>
  );
}
```

**`<AdTogetherBanner>` props:**
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `adUnitId` | `string` | `'default'` | Optional label for this ad placement (e.g. `'home_banner'`, `'chat_bottom'`). Used for analytics grouping only — not validated server-side. |
| `showCloseButton` | `boolean` | `false` | Show a dismissable close button overlay |
| `onAdClosed` | `() => void` | — | Fires when user closes the ad |
| `theme` | `'dark' \| 'light' \| 'auto'` | `'auto'` | Color scheme |
| `onAdLoaded` | `() => void` | — | Fires when ad is fetched |
| `onAdFailedToLoad` | `(error: Error) => void` | — | Fires on fetch failure |
| `style` | `StyleProp<ViewStyle>` | — | React Native styles |

### Interstitial Ad

```tsx
import { useState } from 'react';
import { View, Button } from 'react-native';
import { AdTogetherInterstitial } from '@adtogether/react-native-sdk';

function MyScreen() {
  const [showAd, setShowAd] = useState(false);

  return (
    <View style={{ flex: 1, justifyContent: 'center' }}>
      <Button title="Show Interstitial" onPress={() => setShowAd(true)} />

      <AdTogetherInterstitial
        adUnitId="level_complete" // optional placement label
        isOpen={showAd}
        onClose={() => setShowAd(false)}
        closeDelay={5}
        onAdLoaded={() => console.log('Interstitial loaded')}
      />
    </View>
  );
}
```

**`<AdTogetherInterstitial>` props:**
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `adUnitId` | `string` | `'default'` | Optional label for this ad placement. Used for analytics grouping only. |
| `isOpen` | `boolean` | **required** | Controls visibility |
| `onClose` | `() => void` | **required** | Called when user closes |
| `closeDelay` | `number` | `3` | Seconds before close button appears |
| `theme` | `'dark' \| 'light' \| 'auto'` | `'auto'` | Color scheme |
| `onAdLoaded` | `() => void` | — | Fires when ad is fetched |
| `onAdFailedToLoad` | `(error: Error) => void` | — | Fires on fetch failure |