Installation

Ask AI about this page

@qartvelo/react-native-ads brings Qartvelo Ads banner, interstitial and rewarded ads to React Native apps on Android. It is a thin bridge: campaign selection, timeouts, AdMob fallback, request de-duplication and the reward-once guarantee all run in the native Kotlin SDK. The JavaScript layer validates arguments, returns typed results and forwards events.

New Architecture only: a TurboModule (NativeQartveloAds) and a Fabric component (QartveloAdsBannerView), generated by codegen and autolinked.
Android only for now. On iOS and web every promise rejects with unsupported_platform, <QartveloAdsBanner /> renders nothing and QartveloAds.isSupported() returns false, so shared code runs everywhere.

Requirements


React Native	0.79 or newer with the New Architecture enabled (`newArchEnabled=true`, the default)
Android	minSdk 24, compileSdk 35 or newer
Build JDK	17
Expo	Bare workflow or a development build (`expo prebuild`); not Expo Go

Tested with React Native 0.87.1 (React 19.2).

1. Install the package

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

2. Add JitPack

The plugin depends on the native SDK com.qartvelo.ads:core:0.3.0 from JitPack. Add the repository to every project:

allprojects {
    repositories {
        maven {
            url "https://jitpack.io"
            content { includeGroup("com.qartvelo.ads") }
        }
    }
}

3. Enable the AdMob fallback (optional)

By default only the core SDK is included and a Qartvelo Ads no-fill simply reports “no ad”. To fall back to your own AdMob units:

QartveloAds_admobEnabled=true
# Optional: pin a different native SDK version (default 0.3.0)
# QartveloAds_sdkVersion=0.3.0

This adds com.qartvelo.ads:admob, which brings Google’s play-services-ads (25.4.0). Google requires your AdMob App ID in the manifest, or the app crashes at start-up:

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

Google’s sample App ID ca-app-pub-3940256099942544~3347511713 works for development.

4. Rebuild

The TurboModule and banner component are compiled into the app, so rebuild after installing or upgrading:

npx react-native run-android

A JavaScript reload is not enough: calls reject with module_unavailable until the native app is rebuilt.

Local backend over HTTP (debug only)

For a local backend at http://10.0.2.2:8000/, allow cleartext in debug builds:

<network-security-config>
  <domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="false">10.0.2.2</domain>
    <domain includeSubdomains="false">localhost</domain>
  </domain-config>
</network-security-config>

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
  <application
      android:networkSecurityConfig="@xml/network_security_config"
      tools:ignore="UnusedAttribute" />
</manifest>

localhost keeps Metro working on physical devices through adb reverse tcp:8081 tcp:8081.

Next: Usage.