# Installation

> Install @qartvelo/react-native-ads and configure the Android build.

Source: https://developers.qartvelo.com/react-native/installation

`@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](/android/installation/). 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

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

```groovy title="android/build.gradle"
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:

```properties title="android/gradle.properties"
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:

```xml title="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>
```

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:

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

```xml title="android/app/src/debug/res/xml/network_security_config.xml"
<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>
```

```xml title="android/app/src/debug/AndroidManifest.xml"
<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](/react-native/usage/).