Getting Started with Advergic React Native SDK

Welcome! This guide will help you integrate mobile advertising into your React Native app in just a few minutes.

📋 Prerequisites

• React Native: 0.71 or higher (works on both the old and new architecture)
• Node.js: 18.0 or higher
• Android: API 24+ (Android 7.0) for Android apps
• iOS: 15.0+ for iOS apps
• API Key: Get one from app.advergic.com

🚀 5-Minute Setup

Step 1: Install the SDK

npm install @advergic-ads/react-native-sdk

or with Yarn:

yarn add @advergic-ads/react-native-sdk

Step 2: Android Setup (One Line!)

Add your Google Ads Application ID to android/app/src/main/AndroidManifest.xml:

<application>
  <meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy" />
</application>

Get your ID from AdMob Console.

That's it! React Native auto-linking handles the rest.

Step 3: iOS Setup

The React Native module is auto-linked, but the native AdvergicSDK is not published on the CocoaPods trunk — it ships from Advergic's own podspec. Add that one line to your Podfile (alongside the iOS 15.0 deployment target), then install:

# ios/Podfile
platform :ios, '15.0'

target 'YourApp' do
  # ...existing config (use_react_native! etc.)...

  # Required: makes the native Advergic iOS SDK resolvable by CocoaPods.
  pod 'AdvergicSDK', :podspec => 'https://app.advergic.com/ios/sdk/AdvergicSDK.podspec'
end

cd ios && pod install && cd ..

Once that line is present, CocoaPods resolves AdvergicReactNative (auto-linked) and its AdvergicSDK dependency, and pulls in Google Mobile Ads automatically. Prebid is bundled inside the AdvergicSDK framework.

Why the extra line? CocoaPods can only resolve a pod's dependencies from the trunk or from sources declared in your Podfile. Since AdvergicSDK is distributed via a hosted podspec rather than the trunk, the consuming app must point CocoaPods at it. The hosted URL always serves the latest SDK version.

Note: iOS supports banner, interstitial, rewarded, and app-open ads. Native ads are currently Android-only.

Step 4: Initialize in Your App

import React, { useEffect } from "react";
import Advergic from "@advergic-ads/react-native-sdk";

export default function App() {
  useEffect(() => {
    // Initialize the SDK on app launch
    Advergic.initialize("YOUR_API_KEY").then((initialized) => {
      if (initialized) {
        console.log("✓ Advergic SDK ready!");
      }
    });
  }, []);

  return (
    // Your app content
  );
}

Step 5: Add Your First Banner Ad

import { AdvergicBannerAd } from "@advergic-ads/react-native-sdk";

export default function Home() {
  return (
    <View>
      {/* Your content */}
      
      <AdvergicBannerAd
        adUnitId="/23315275002/home_banner_320x50_ad_unit_id"
        style={{ width: 320, height: 50, alignSelf: "center" }}
        onAdLoaded={() => console.log("Ad loaded!")}
        onAdFailedToLoad={(error) => console.error("Ad failed:", error)}
      />
    </View>
  );
}

That's it! You now have banner ads running. 🎉

📦 Ad Formats

The SDK supports 4 ad formats:

1. Banner Ads ✓ Easiest

Rectangular ads that display inline with your content.

<AdvergicBannerAd
  adUnitId="/YOUR_NETWORK_ID/YOUR_BANNER_AD_UNIT"
  style={{ width: 320, height: 50 }}
/>

Common sizes:

• 320x50 — Standard mobile banner
• 300x250 — Medium rectangle
• 320x100 — Large banner
• 300x600 — Half page

2. Interstitial Ads — Full Screen

Full-screen ads shown between content (e.g., between game levels, after article read).

import Advergic from "@advergic-ads/react-native-sdk";

// Show when appropriate
Advergic.showInterstitialAd("/YOUR_NETWORK_ID/YOUR_INTERSTITIAL_AD_UNIT");

// Listen for close
Advergic.onInterstitialAdClosed(() => {
  console.log("User closed the ad");
});

3. Rewarded Ads — Earn Points

Video ads that reward users for watching (unlock premium, earn coins, etc.).

// Show when user wants premium content
Advergic.showRewardedAd("/YOUR_NETWORK_ID/YOUR_REWARDED_AD_UNIT");

// Listen for reward grant
Advergic.onRewardedAdUserEarnedReward(() => {
  unlockPremiumContent();
});

4. Native Ads — Custom Design

Get ad data and render it your own way.

const nativeAd = await Advergic.loadNativeAd("/YOUR_NETWORK_ID/YOUR_NATIVE_AD_UNIT");

return (
  <View>
    <Image source={{ uri: nativeAd.mainImage }} />
    <Text>{nativeAd.title}</Text>
    <Button title={nativeAd.callToAction} />
  </View>
);

📱 Your First Complete App

Here's a minimal app with both banner and interstitial ads:

import React, { useEffect, useState } from "react";
import { View, Text, Button, StyleSheet, ScrollView } from "react-native";
import Advergic, { AdvergicBannerAd } from "@advergic-ads/react-native-sdk";

const API_KEY = "YOUR_API_KEY";

export default function App() {
  const [initialized, setInitialized] = useState(false);

  useEffect(() => {
    // Initialize SDK
    Advergic.initialize(API_KEY).then(setInitialized);

    // Listen for interstitial close
    const sub = Advergic.onInterstitialAdClosed(() => {
      console.log("Interstitial closed");
    });

    return () => sub.remove();
  }, []);

  const showInterstitial = () => {
    if (initialized) {
      Advergic.showInterstitialAd(
        "/23315275002/start_game_interstitial_ad_unit_id"
      );
    }
  };

  return (
    <ScrollView style={styles.container}>
      <Text style={styles.title}>My App</Text>

      {/* Top banner ad */}
      <AdvergicBannerAd
        adUnitId="/23315275002/home_banner_320x50_ad_unit_id"
        style={{ width: 320, height: 50, alignSelf: "center" }}
      />

      {/* App content */}
      <Text style={styles.text}>Welcome to your app!</Text>

      <Button
        title="Show Interstitial Ad"
        onPress={showInterstitial}
        disabled={!initialized}
      />

      {/* Bottom banner ad */}
      <AdvergicBannerAd
        adUnitId="/23315275002/home_screen_top_banner_video_300x250_ad_unit_id"
        style={{ width: 300, height: 250, alignSelf: "center", marginVertical: 20 }}
      />
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 20, backgroundColor: "#f5f5f5" },
  title: { fontSize: 28, fontWeight: "bold", marginBottom: 20 },
  text: { fontSize: 16, marginBottom: 20, color: "#333" },
});

🔑 Getting Your API Key & Ad Unit IDs

1. Sign up at app.advergic.com
2. Create a new app
3. Copy your API Key (use in Advergic.initialize())
4. Go to Inventory → Ad Units to create ad units
5. Copy the Ad Unit IDs and use them in your components

🐛 Troubleshooting

"Banner is blank"

• Ensure Advergic.initialize() is called before rendering banners
• Check that the app has internet access
• Verify the ad unit ID is correct
• Add onAdFailedToLoad callback to see error details

"Interstitial doesn't show"

• Make sure you're using the correct ad unit ID (should be an interstitial, not banner)
• Call showInterstitialAd() after the app is initialized
• Some devices may not have ads available; add error handling

"Module not found" on Android

• Run npm install again
• Try npm start -- --reset-cache to clear React Native cache
• Delete node_modules and reinstall if still broken

Debug Mode

Enable verbose logging in Android logcat:

adb logcat | grep -E "Advergic|Banner"

📚 Next Steps

• Read the full docs: README.md
• Check examples: examples/dramafy/
• API Reference: README.md → API Reference
• Troubleshooting: README.md → Troubleshooting

💡 Tips

✅ Do:

• Use fixed pixel dimensions for banner size (not percentages)
• Initialize SDK early in your app lifecycle
• Test with your own app before going live
• Monitor fill rates in the dashboard

❌ Don't:

• Change ad unit IDs frequently (disrupts analytics)
• Show multiple ads simultaneously in the same location
• Initialize the SDK multiple times

🤝 Need Help?

• Email: [email protected]