@bigcrunch/react-native-ads 0.3.0 → 0.3.1

package/README.md

@@ -4,12 +4,20 @@ Simplified in-app advertising for React Native apps with Prebid and Google Ad Ma
 
 ## Features
 
-- 🎯 **Simple Integration**: One SDK to handle Prebid, Google Ad Manager, and Amazon demand
-- 📊 **Built-in Analytics**: Automatic tracking of impressions, clicks, and revenue
-- 💰 **Revenue Optimization**: Server-side header bidding via Prebid Server
-- 🔧 **Configuration-Driven**: Manage placements from BigCrunch dashboard
-- 📱 **Cross-Platform**: Supports both iOS and Android
-- 🎨 **Ad Formats**: Banner, Interstitial, and Rewarded ads
+- **Simple Integration**: One SDK to handle Prebid, Google Ad Manager, and Amazon demand
+- **Built-in Analytics**: Automatic tracking of screen views, impressions, clicks, and revenue
+- **Revenue Optimization**: Server-side header bidding via Prebid Server
+- **Configuration-Driven**: Manage placements and ad sizes from the BigCrunch dashboard
+- **Cross-Platform**: Supports both iOS and Android
+- **Ad Formats**: Banner, Interstitial, and Rewarded ads
+
+## Requirements
+
+- React Native 0.60+
+- iOS 13.0+
+- Android API 21+
+- **Bare React Native** project (not Expo managed workflow)
+  - If using Expo, you must first run `expo prebuild` to generate native directories
 
 ## Installation
 
@@ -22,248 +30,318 @@ yarn add @bigcrunch/react-native-ads
 ### iOS Setup
 
 ```bash
-cd ios && pod install
+cd ios && pod install && cd ..
 ```
 
 Add the following to your `Info.plist`:
 
 ```xml
 <key>GADApplicationIdentifier</key>
-<string>YOUR_ADMOB_APP_ID</string>
-
-<key>SKAdNetworkItems</key>
-<array>
-  <!-- Add SKAdNetwork identifiers -->
-</array>
+<string>YOUR_GAM_APP_ID</string>
 ```
 
+> For testing, you can use the Google test ID: `ca-app-pub-3940256099942544~1458002511`
+
 ### Android Setup
 
-Add the following to your `AndroidManifest.xml`:
+Add the following inside the `<application>` tag in your `AndroidManifest.xml`:
 
 ```xml
 <meta-data
     android:name="com.google.android.gms.ads.APPLICATION_ID"
-    android:value="YOUR_ADMOB_APP_ID"/>
+    android:value="YOUR_GAM_APP_ID"/>
 ```
 
+> For testing, you can use: `ca-app-pub-3940256099942544~3347511713`
+
 ## Quick Start
 
 ### 1. Initialize the SDK
 
 ```typescript
+import { useEffect } from 'react';
 import { BigCrunchAds } from '@bigcrunch/react-native-ads';
 
-// Initialize at app startup (e.g., in App.tsx)
-async function initializeAds() {
-  try {
-    await BigCrunchAds.initialize(
-      'your-property-id',
-      'production' // or 'sandbox'
-    );
-    console.log('BigCrunch Ads initialized successfully');
-  } catch (error) {
-    console.error('Failed to initialize BigCrunch Ads:', error);
-  }
-}
+const PROPERTY_ID = 'YOUR_PROPERTY_ID';
+
+function App() {
+  useEffect(() => {
+    initializeBigCrunch();
+  }, []);
 
-// Call on app launch
-initializeAds();
+  const initializeBigCrunch = async () => {
+    try {
+      await BigCrunchAds.initialize(PROPERTY_ID, 'production');
+      console.log('BigCrunch SDK initialized');
+    } catch (error) {
+      console.error('BigCrunch initialization failed:', error);
+    }
+  };
+
+  return (
+    // Your app content
+  );
+}
 ```
 
+| Parameter | Description |
+|-----------|-------------|
+| `PROPERTY_ID` | Unique identifier for your app, provided by BigCrunch |
+| `environment` | `'production'` for live apps, `'sandbox'` for testing |
+
 ### 2. Track Screen Views
 
 ```typescript
+import { useEffect } from 'react';
 import { BigCrunchAds } from '@bigcrunch/react-native-ads';
 
-// Track screen views for analytics
-BigCrunchAds.trackScreenView('HomeScreen');
+function HomeScreen() {
+  useEffect(() => {
+    BigCrunchAds.trackScreenView('HomeScreen');
+  }, []);
+
+  return (
+    // Screen content
+  );
+}
 ```
 
+> For automatic tracking with React Navigation, see the [Tracking-Only Integration Guide](./docs/TRACKING_ONLY_INTEGRATION.md#option-b-automatic-tracking-with-react-navigation-recommended).
+
 ## Ad Formats
 
 ### Banner Ads
 
+Ad sizes are configured per placement in the BigCrunch dashboard. You only need to pass the `placementId` — the SDK handles the rest.
+
 ```tsx
 import { BigCrunchBannerView } from '@bigcrunch/react-native-ads';
 
-function HomeScreen() {
+function ArticleScreen() {
   return (
-    <View>
-      {/* Your content */}
+    <View style={{ flex: 1 }}>
+      <Text>Article content...</Text>
 
       <BigCrunchBannerView
-        placementId="banner-home"
-        size="BANNER" // or "MEDIUM_RECTANGLE", "ADAPTIVE", etc.
-        style={{ alignSelf: 'center' }}
+        placementId="your-banner-placement"
         onAdLoaded={() => console.log('Banner loaded')}
-        onAdFailedToLoad={(error) => console.error('Banner failed:', error)}
-        onAdRevenue={(revenue) => console.log('Revenue:', revenue)}
+        onAdFailedToLoad={(error) => console.error('Banner failed:', error.message)}
       />
     </View>
   );
 }
 ```
 
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placementId` | `string` | *required* | Placement ID from the BigCrunch dashboard |
+| `size` | `BannerSize \| { width, height }` | *from config* | Optional size override. If omitted, uses the size from placement config. |
+| `autoLoad` | `boolean` | `true` | Automatically load ad on mount |
+| `refreshInterval` | `number` | `0` | Auto-refresh interval in seconds (0 = disabled) |
+| `customTargeting` | `Record<string, string>` | — | Custom key-value targeting |
+| `style` | `ViewStyle` | — | Container style |
+
+#### Callbacks
+
+| Callback | Description |
+|----------|-------------|
+| `onAdLoaded` | Ad loaded successfully |
+| `onAdFailedToLoad` | Ad failed to load. Receives `AdError` with `code` and `message`. |
+| `onAdImpression` | Ad impression recorded |
+| `onAdClicked` | User tapped the ad |
+| `onAdOpened` | Ad opened an overlay |
+| `onAdClosed` | Ad overlay closed |
+| `onAdRevenue` | Revenue event received (ILRD). Receives `AdRevenue` with `valueMicros` and `currencyCode`. |
+
 #### Available Banner Sizes
 
-- `BANNER` - 320x50
-- `LARGE_BANNER` - 320x100
-- `MEDIUM_RECTANGLE` - 300x250
-- `FULL_BANNER` - 468x60
-- `LEADERBOARD` - 728x90
-- `ADAPTIVE` - Full-width adaptive banner (recommended). Google calculates the optimal height for the device screen width.
-- `SMART` - Deprecated, alias for `ADAPTIVE`
-- Custom size: `{ width: 300, height: 250 }`
+| Size | Dimensions | Description |
+|------|-----------|-------------|
+| `'BANNER'` | 320x50 | Standard banner |
+| `'LARGE_BANNER'` | 320x100 | Large banner |
+| `'MEDIUM_RECTANGLE'` | 300x250 | Medium rectangle (MREC) |
+| `'FULL_BANNER'` | 468x60 | Full-size banner |
+| `'LEADERBOARD'` | 728x90 | Leaderboard (tablets) |
+| `'ADAPTIVE'` | Full width, auto height | Adaptive banner (recommended) |
 
 ### Interstitial Ads
 
+Full-screen ads shown at natural transition points. Preload ahead of time, then show when ready.
+
 ```typescript
+import { useEffect, useRef } from 'react';
 import { BigCrunchInterstitial } from '@bigcrunch/react-native-ads';
+import type { EventSubscription } from '@bigcrunch/react-native-ads';
+
+const PLACEMENT_ID = 'interstitial-level-complete';
+
+function GameScreen() {
+  const subscriptions = useRef<EventSubscription[]>([]);
+
+  useEffect(() => {
+    // Preload on mount
+    BigCrunchInterstitial.load({ placementId: PLACEMENT_ID });
+
+    // Set up listeners
+    subscriptions.current.push(
+      BigCrunchInterstitial.addEventListener(PLACEMENT_ID, 'adClosed', () => {
+        // Preload the next interstitial
+        BigCrunchInterstitial.load({ placementId: PLACEMENT_ID });
+      }),
+      BigCrunchInterstitial.addEventListener(PLACEMENT_ID, 'adFailedToLoad', (event) => {
+        console.error('Interstitial failed:', event.error.message);
+      })
+    );
 
-// Load an interstitial
-async function loadInterstitial() {
-  try {
-    await BigCrunchInterstitial.load({
-      placementId: 'interstitial-level-complete'
-    });
-    console.log('Interstitial loaded');
-  } catch (error) {
-    console.error('Failed to load interstitial:', error);
-  }
-}
+    return () => {
+      subscriptions.current.forEach((sub) => sub.remove());
+      BigCrunchInterstitial.destroy(PLACEMENT_ID);
+    };
+  }, []);
 
-// Show the interstitial
-async function showInterstitial() {
-  const isLoaded = await BigCrunchInterstitial.isLoaded('interstitial-level-complete');
+  const handleLevelComplete = async () => {
+    if (await BigCrunchInterstitial.isLoaded(PLACEMENT_ID)) {
+      await BigCrunchInterstitial.show(PLACEMENT_ID);
+    }
+  };
 
-  if (isLoaded) {
-    await BigCrunchInterstitial.show('interstitial-level-complete');
-  }
+  return (
+    <Button title="Complete Level" onPress={handleLevelComplete} />
+  );
 }
-
-// Listen for events
-BigCrunchInterstitial.addEventListener(
-  'interstitial-level-complete',
-  'adClosed',
-  () => {
-    console.log('Interstitial closed');
-    // Load next ad or continue game
-  }
-);
 ```
 
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `load(options)` | Load an interstitial ad |
+| `show(placementId)` | Show a loaded interstitial |
+| `isLoaded(placementId)` | Check if an ad is loaded |
+| `destroy(placementId)` | Destroy an interstitial instance |
+| `addEventListener(placementId, event, listener)` | Add an event listener |
+
+#### Events
+
+| Event | Description |
+|-------|-------------|
+| `'adLoaded'` | Ad loaded and ready to show |
+| `'adFailedToLoad'` | Loading failed |
+| `'adImpression'` | Impression recorded |
+| `'adClicked'` | User tapped the ad |
+| `'adOpened'` | Full-screen ad presented |
+| `'adClosed'` | User dismissed the ad |
+| `'adRevenue'` | Revenue event (ILRD) |
+
 ### Rewarded Ads
 
+Full-screen ads that offer the user an in-app reward in exchange for watching. The API is identical to interstitials, with the addition of the `rewardEarned` event.
+
 ```typescript
+import { useEffect, useRef, useState } from 'react';
+import { Button, Alert } from 'react-native';
 import { BigCrunchRewarded } from '@bigcrunch/react-native-ads';
+import type { EventSubscription } from '@bigcrunch/react-native-ads';
+
+const PLACEMENT_ID = 'rewarded-extra-life';
+
+function GameOverScreen() {
+  const [adReady, setAdReady] = useState(false);
+  const subscriptions = useRef<EventSubscription[]>([]);
+
+  useEffect(() => {
+    BigCrunchRewarded.load({ placementId: PLACEMENT_ID });
+
+    subscriptions.current.push(
+      BigCrunchRewarded.addEventListener(PLACEMENT_ID, 'adLoaded', () => {
+        setAdReady(true);
+      }),
+      BigCrunchRewarded.addEventListener(PLACEMENT_ID, 'adClosed', () => {
+        setAdReady(false);
+        BigCrunchRewarded.load({ placementId: PLACEMENT_ID });
+      }),
+      BigCrunchRewarded.addEventListener(PLACEMENT_ID, 'rewardEarned', (event) => {
+        Alert.alert('Reward!', `You earned ${event.rewardAmount} ${event.rewardType}`);
+      })
+    );
 
-// Load a rewarded ad
-async function loadRewardedAd() {
-  try {
-    await BigCrunchRewarded.load({
-      placementId: 'rewarded-extra-life'
-    });
-    console.log('Rewarded ad loaded');
-  } catch (error) {
-    console.error('Failed to load rewarded ad:', error);
-  }
-}
+    return () => {
+      subscriptions.current.forEach((sub) => sub.remove());
+      BigCrunchRewarded.destroy(PLACEMENT_ID);
+    };
+  }, []);
+
+  const handleWatchAd = async () => {
+    if (await BigCrunchRewarded.isLoaded(PLACEMENT_ID)) {
+      await BigCrunchRewarded.show(PLACEMENT_ID);
+    }
+  };
 
-// Set up reward listener
-BigCrunchRewarded.addEventListener(
-  'rewarded-extra-life',
-  'rewardEarned',
-  (event) => {
-    console.log(`User earned ${event.rewardAmount} ${event.rewardType}`);
-    // Grant reward to user
-  }
-);
-
-// Show the rewarded ad
-async function showRewardedAd() {
-  const isLoaded = await BigCrunchRewarded.isLoaded('rewarded-extra-life');
-
-  if (isLoaded) {
-    await BigCrunchRewarded.show('rewarded-extra-life');
-  } else {
-    console.log('Rewarded ad not ready');
-  }
+  return (
+    <Button title="Watch Ad for Extra Life" onPress={handleWatchAd} disabled={!adReady} />
+  );
 }
 ```
 
-## Advanced Features
+#### Additional Events
 
-### Custom Targeting
+All interstitial events plus:
 
-```typescript
-// Banner with custom targeting
-<BigCrunchBannerView
-  placementId="banner-home"
-  customTargeting={{
-    'user_level': '5',
-    'game_mode': 'survival'
-  }}
-/>
-
-// Interstitial with custom targeting
-await BigCrunchInterstitial.load({
-  placementId: 'interstitial-level-complete',
-  customTargeting: {
-    'level': '10',
-    'score': 'high'
-  }
-});
-```
+| Event | Description |
+|-------|-------------|
+| `'rewardEarned'` | User completed the ad and earned a reward. Includes `rewardType` (string) and `rewardAmount` (number). |
 
-### Privacy Settings
+## Privacy & Compliance
 
 ```typescript
-// GDPR Consent
-await BigCrunchAds.setGdprConsent('consent_string_here');
+// GDPR — pass IAB TCF consent string
+await BigCrunchAds.setGdprConsent('consent-string-here');
 
-// CCPA Compliance
+// CCPA — pass IAB US Privacy string
 await BigCrunchAds.setCcpaString('1YNN');
 
-// COPPA Compliance
+// COPPA — for apps directed at children
 await BigCrunchAds.setCoppaCompliant(true);
 ```
 
-### Debug Mode & Test Devices
+## Verifying Your Integration
 
 ```typescript
-// Enable debug mode
+// Check if SDK is initialized
+const isReady = await BigCrunchAds.isInitialized();
+console.log('SDK initialized:', isReady);
+
+// Get session information
+const session = await BigCrunchAds.getSessionInfo();
+console.log('Session ID:', session.sessionId);
+console.log('Screen views:', session.screenViewCount);
+
+// Enable debug logging during development
 await BigCrunchAds.setDebugMode(true);
 
-// Add test devices
+// Register test devices to receive test ads
 await BigCrunchAds.addTestDevice('YOUR_DEVICE_ID');
 ```
 
-### Event Listeners
+> **Finding your device ID:** Run your app with debug mode enabled, load an ad, and check the console output. The Google Mobile Ads SDK will log your device ID.
 
-```typescript
-// Global configuration events
-BigCrunchAds.onConfigUpdated((config) => {
-  console.log('Config updated:', config);
-});
-
-// Session events
-BigCrunchAds.onSessionStarted((session) => {
-  console.log('New session started:', session.sessionId);
-});
-
-// Ad-specific events
-const subscription = BigCrunchInterstitial.addEventListener(
-  'interstitial-main',
-  'adRevenue',
-  (event) => {
-    console.log('Revenue received:', event.revenue);
-  }
-);
-
-// Remove listener when done
-subscription.remove();
-```
+## Error Codes
+
+When an ad fails to load, the `AdError` object contains a `code` and `message`:
+
+| Code | Description |
+|------|-------------|
+| `NETWORK_ERROR` | No network connectivity |
+| `NO_FILL` | No ad available for this request |
+| `INVALID_REQUEST` | Malformed ad request |
+| `INTERNAL_ERROR` | Internal SDK error |
+| `INVALID_PLACEMENT` | Placement ID not found in config |
+| `NOT_INITIALIZED` | SDK not yet initialized |
+| `ALREADY_LOADED` | An ad is already loaded for this placement |
+| `NOT_LOADED` | Attempted to show an ad that isn't loaded |
+| `TIMEOUT` | Ad request timed out |
 
 ## TypeScript Support
 
@@ -274,137 +352,53 @@ import type {
   AdError,
   AdRevenue,
   BannerSize,
+  CustomSize,
   PlacementConfig,
-  SessionInfo
+  AppConfig,
+  SessionInfo,
+  EventSubscription,
+  AdErrorCode,
 } from '@bigcrunch/react-native-ads';
 ```
 
-## API Reference
-
-### BigCrunchAds
-
-| Method | Description |
-|--------|-------------|
-| `initialize(propertyId, environment)` | Initialize the SDK |
-| `trackScreenView(screenName)` | Track a screen view |
-| `getAppConfig()` | Get current app configuration |
-| `getSessionInfo()` | Get current session information |
-| `setGdprConsent(consent)` | Set GDPR consent string |
-| `setCcpaString(ccpaString)` | Set CCPA compliance string |
-| `setCoppaCompliant(isCompliant)` | Set COPPA compliance |
-| `setDebugMode(enabled)` | Enable/disable debug mode |
-
-### BigCrunchBannerView Props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `placementId` | string | Required. Placement ID from dashboard |
-| `size` | BannerSize \| CustomSize | Banner size (default: BANNER) |
-| `autoLoad` | boolean | Auto-load ad on mount (default: true) |
-| `refreshInterval` | number | Auto-refresh interval in seconds |
-| `customTargeting` | object | Custom targeting parameters |
-| `onAdLoaded` | function | Called when ad loads |
-| `onAdFailedToLoad` | function | Called on load failure |
-| `onAdImpression` | function | Called on impression |
-| `onAdClicked` | function | Called on click |
-| `onAdRevenue` | function | Called on revenue (ILRD) |
-
-### BigCrunchInterstitial
-
-| Method | Description |
-|--------|-------------|
-| `load(options)` | Load an interstitial ad |
-| `show(placementId)` | Show a loaded interstitial |
-| `isLoaded(placementId)` | Check if ad is loaded |
-| `destroy(placementId)` | Destroy an interstitial instance |
-| `addEventListener(placementId, event, listener)` | Add event listener |
-
-### BigCrunchRewarded
-
-| Method | Description |
-|--------|-------------|
-| `load(options)` | Load a rewarded ad |
-| `show(placementId)` | Show a loaded rewarded ad |
-| `isLoaded(placementId)` | Check if ad is loaded |
-| `destroy(placementId)` | Destroy a rewarded instance |
-| `addEventListener(placementId, event, listener)` | Add event listener |
-| `onRewardEarned(placementId, listener)` | Listen for rewards |
-
-## Error Handling
-
-```typescript
-import { AdErrorCode } from '@bigcrunch/react-native-ads';
-
-// Handle banner errors
-<BigCrunchBannerView
-  placementId="banner-home"
-  onAdFailedToLoad={(error) => {
-    switch (error.code) {
-      case AdErrorCode.NO_FILL:
-        console.log('No ads available');
-        break;
-      case AdErrorCode.NETWORK_ERROR:
-        console.log('Network error');
-        break;
-      case AdErrorCode.INVALID_PLACEMENT:
-        console.log('Invalid placement ID');
-        break;
-      default:
-        console.error('Ad error:', error.message);
-    }
-  }}
-/>
-```
+## Full Documentation
 
-## Example App
+- [Full Integration Guide (Tracking + Ads)](./docs/FULL_INTEGRATION.md)
+- [Tracking-Only Integration Guide](./docs/TRACKING_ONLY_INTEGRATION.md)
+- [Google Ad Manager Setup](./docs/GOOGLE_SETUP.md)
+- [Testing Guide](./docs/TESTING_GUIDE.md)
+- [Example App](./example)
 
-Check out the [example app](./example) for a complete implementation:
+## Troubleshooting
 
+### iOS: Pod install fails
 ```bash
-cd react-native/example
-npm install
-npm run ios # or npm run android
+cd ios
+pod deintegrate
+pod cache clean --all
+pod install
 ```
 
-## Troubleshooting
-
-### iOS Issues
-
-1. **Module not found**: Run `cd ios && pod install`
-2. **Build failures**: Clean build folder and rebuild
-3. **App crashes on launch**: Verify GADApplicationIdentifier in Info.plist
-
-### Android Issues
-
-1. **Manifest merger failed**: Check APPLICATION_ID in AndroidManifest.xml
-2. **Build failures**: Sync project with Gradle files
-3. **MultiDex issues**: Enable multidex in your app
-
-### Common Issues
-
-1. **Ads not loading**:
-   - Verify initialization is complete
-   - Check placement IDs match dashboard
-   - Ensure test mode is disabled in production
-
-2. **Revenue not tracking**:
-   - Verify ILRD is enabled in Google Ad Manager
-   - Check revenue event listeners are set up
-
-3. **TypeScript errors**:
-   - Update to latest version
-   - Rebuild TypeScript definitions: `npm run typescript`
-
-## Requirements
-
-- React Native 0.60+
-- iOS 13.0+
-- Android API 21+
-- TypeScript 4.0+ (optional)
+### Android: Build fails with duplicate classes
+Add to `android/app/build.gradle`:
+```gradle
+android {
+    packagingOptions {
+        pickFirst 'META-INF/*'
+    }
+}
+```
 
-## License
+### Ads not loading ("No Fill")
+- Normal during testing — ad inventory varies by region and time
+- Register your device as a test device to receive test ads
+- Verify placement IDs match the BigCrunch dashboard
+- Check the GAM App ID in `Info.plist` / `AndroidManifest.xml`
 
-MIT
+### Interstitial/Rewarded not showing
+- Call `load()` before `show()`
+- Check `isLoaded()` before calling `show()`
+- Listen for `adFailedToLoad` events to diagnose issues
 
 ## Support
 
@@ -412,6 +406,6 @@ MIT
 - Issues: https://github.com/bigcrunch/mobile-ads-sdk/issues
 - Email: support@bigcrunch.com
 
-## Contributing
+## License
 
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for details.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigcrunch/react-native-ads",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "BigCrunch Mobile Ads SDK for React Native - Simplified in-app advertising with Prebid and Google Ad Manager",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",