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

npm install @bigcrunch/react-native-ads
# or
yarn add @bigcrunch/react-native-ads

iOS Setup

cd ios && pod install

Add the following to your Info.plist:

<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:

<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="YOUR_ADMOB_APP_ID"/>

Quick Start

1. Initialize the SDK

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

import { BigCrunchAds } from '@bigcrunch/react-native-ads';

// Track screen views for analytics
BigCrunchAds.trackScreenView('HomeScreen');

Ad Formats

Banner Ads

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

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

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

// 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

// GDPR Consent
await BigCrunchAds.setGdprConsent('consent_string_here');

// CCPA Compliance
await BigCrunchAds.setCcpaString('1YNN');

// COPPA Compliance
await BigCrunchAds.setCoppaCompliant(true);

Debug Mode & Test Devices

// Enable debug mode
await BigCrunchAds.setDebugMode(true);

// Add test devices
await BigCrunchAds.addTestDevice('YOUR_DEVICE_ID');

Event Listeners

// 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:

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

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 for a complete implementation:

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: [email protected]

Contributing

See CONTRIBUTING.md for details.