@bigcrunch/react-native-ads 0.1.0

package/README.md

@@ -0,0 +1,417 @@
+# BigCrunch Mobile Ads SDK for React Native
+
+Simplified in-app advertising for React Native apps with Prebid and Google Ad Manager integration.
+
+## 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
+
+## Installation
+
+```bash
+npm install @bigcrunch/react-native-ads
+# or
+yarn add @bigcrunch/react-native-ads
+```
+
+### iOS Setup
+
+```bash
+cd ios && pod install
+```
+
+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>
+```
+
+### Android Setup
+
+Add the following to your `AndroidManifest.xml`:
+
+```xml
+<meta-data
+    android:name="com.google.android.gms.ads.APPLICATION_ID"
+    android:value="YOUR_ADMOB_APP_ID"/>
+```
+
+## Quick Start
+
+### 1. Initialize the SDK
+
+```typescript
+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',
+      'your-api-key',
+      'production' // or 'sandbox'
+    );
+    console.log('BigCrunch Ads initialized successfully');
+  } catch (error) {
+    console.error('Failed to initialize BigCrunch Ads:', error);
+  }
+}
+
+// Call on app launch
+initializeAds();
+```
+
+### 2. Track Screen Views
+
+```typescript
+import { BigCrunchAds } from '@bigcrunch/react-native-ads';
+
+// Track screen views for analytics
+BigCrunchAds.trackScreenView('HomeScreen');
+```
+
+## Ad Formats
+
+### Banner Ads
+
+```tsx
+import { BigCrunchBannerView } from '@bigcrunch/react-native-ads';
+
+function HomeScreen() {
+  return (
+    <View>
+      {/* Your content */}
+
+      <BigCrunchBannerView
+        placementId="banner-home"
+        size="BANNER" // or "MEDIUM_RECTANGLE", "ADAPTIVE", etc.
+        style={{ alignSelf: 'center' }}
+        onAdLoaded={() => console.log('Banner loaded')}
+        onAdFailedToLoad={(error) => console.error('Banner failed:', error)}
+        onAdRevenue={(revenue) => console.log('Revenue:', revenue)}
+      />
+    </View>
+  );
+}
+```
+
+#### Available Banner Sizes
+
+- `BANNER` - 320x50
+- `LARGE_BANNER` - 320x100
+- `MEDIUM_RECTANGLE` - 300x250
+- `FULL_BANNER` - 468x60
+- `LEADERBOARD` - 728x90
+- `ADAPTIVE` - Adaptive banner (recommended)
+- Custom size: `{ width: 300, height: 250 }`
+
+### Interstitial Ads
+
+```typescript
+import { BigCrunchInterstitial } from '@bigcrunch/react-native-ads';
+
+// 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);
+  }
+}
+
+// Show the interstitial
+async function showInterstitial() {
+  const isLoaded = await BigCrunchInterstitial.isLoaded('interstitial-level-complete');
+
+  if (isLoaded) {
+    await BigCrunchInterstitial.show('interstitial-level-complete');
+  }
+}
+
+// Listen for events
+BigCrunchInterstitial.addEventListener(
+  'interstitial-level-complete',
+  'adClosed',
+  () => {
+    console.log('Interstitial closed');
+    // Load next ad or continue game
+  }
+);
+```
+
+### Rewarded Ads
+
+```typescript
+import { BigCrunchRewarded } from '@bigcrunch/react-native-ads';
+
+// 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);
+  }
+}
+
+// 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');
+  }
+}
+```
+
+## Advanced Features
+
+### Custom Targeting
+
+```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'
+  }
+});
+```
+
+### Privacy Settings
+
+```typescript
+// GDPR Consent
+await BigCrunchAds.setGdprConsent('consent_string_here');
+
+// CCPA Compliance
+await BigCrunchAds.setCcpaString('1YNN');
+
+// COPPA Compliance
+await BigCrunchAds.setCoppaCompliant(true);
+```
+
+### Debug Mode & Test Devices
+
+```typescript
+// Enable debug mode
+await BigCrunchAds.setDebugMode(true);
+
+// Add test devices
+await BigCrunchAds.addTestDevice('YOUR_DEVICE_ID');
+```
+
+### Event Listeners
+
+```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();
+```
+
+## TypeScript Support
+
+The SDK includes full TypeScript definitions:
+
+```typescript
+import type {
+  AdError,
+  AdRevenue,
+  BannerSize,
+  PlacementConfig,
+  SessionInfo
+} from '@bigcrunch/react-native-ads';
+```
+
+## API Reference
+
+### BigCrunchAds
+
+| Method | Description |
+|--------|-------------|
+| `initialize(propertyId, apiKey, 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);
+    }
+  }}
+/>
+```
+
+## Example App
+
+Check out the [example app](./example) for a complete implementation:
+
+```bash
+cd react-native/example
+npm install
+npm run ios # or npm run android
+```
+
+## 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)
+
+## License
+
+MIT
+
+## Support
+
+- Documentation: https://docs.bigcrunch.com/mobile-ads-sdk
+- Issues: https://github.com/bigcrunch/mobile-ads-sdk/issues
+- Email: support@bigcrunch.com
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for details.

package/android/build.gradle

@@ -0,0 +1,70 @@
+buildscript {
+    ext.kotlin_version = '1.7.10'
+
+    repositories {
+        google()
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath 'com.android.tools.build:gradle:7.3.1'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+    compileSdkVersion safeExtGet('compileSdkVersion', 34)
+    namespace 'com.bigcrunch.ads.react'
+
+    defaultConfig {
+        minSdkVersion safeExtGet('minSdkVersion', 21)
+        targetSdkVersion safeExtGet('targetSdkVersion', 34)
+        versionCode 1
+        versionName "0.1.0"
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    kotlinOptions {
+        jvmTarget = '1.8'
+        freeCompilerArgs += ['-Xskip-metadata-version-check']
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+    maven { url "https://jitpack.io" }
+}
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+    // React Native dependency
+    implementation 'com.facebook.react:react-native:+'
+
+    // Native Android SDK dependency
+    // This includes all required dependencies (Google Ads, Prebid, OkHttp, Moshi)
+    // as transitive dependencies, eliminating the need for duplication
+    implementation project(':bigcrunch-ads')
+
+    // Coroutines - needed by React Native bridge code
+    // (Native SDK uses 'implementation' so not automatically transitive)
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4'
+}

package/android/settings.gradle

@@ -0,0 +1,6 @@
+// Include the native Android SDK module from the parent directory
+// This allows the React Native Android module to depend on the native SDK
+// and eliminates code duplication
+
+include ':bigcrunch-ads'
+project(':bigcrunch-ads').projectDir = new File(rootProject.projectDir, '../../android/bigcrunch-ads')

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.bigcrunch.ads.react">
+</manifest>