Android · Kotlin

Before you start: you need Android Studio, an app with minSdk 24 or higher, and a placement id from PEP.

1. Add the SDK to your project

   Tell Gradle where to find the SDK, then add it as a dependency. In settings.gradle.kts, inside dependencyResolutionManagement { repositories { … } }:

   settings.gradle.ktsCopy

   maven { url = uri("https://pepecosystem-com.b-cdn.net/sdk/maven") }

   Then in your app module's build.gradle.kts, inside dependencies { … }:

   app/build.gradle.ktsCopy

   implementation("com.pepecosystem:pepads:0.1.1")

   Click Sync Now in Android Studio. The SDK needs no other libraries and adds only the internet permission.

2. Start the SDK once

   Call PepAds.init() when your app starts, passing your app key and app secret. You get both from My Apps → Secrets → Enable Ads, as described above. The best place to call it is your Application class (create one if you don't have it and register it in your manifest with android:name).

   MyApp.ktCopy

   class MyApp : Application() {
       override fun onCreate() {
           super.onCreate()
           PepAds.init(appKey = YOUR_APP_KEY, appSecret = YOUR_APP_SECRET)
           // If you know the signed-in PEP user, tell the SDK — it helps
           // the network apply fair per-user limits. Optional.
           PepAds.setIdentity(currentPepUserId)
       }
   }

   Keep the app secret out of source control and off any screen — store it the way you would any API secret (for example, in your app's BuildConfig from a local, untracked properties file).

3. Show a banner where you want it

   A BannerAdView is a normal Android view. Put it anywhere in your layout — the ad renders at its natural shape inside the width you give it, so a wide leaderboard looks like a leaderboard and a box ad looks like a box.

   KotlinCopy

   val banner = BannerAdView(context)
   yourLayout.addView(banner)   // wherever it belongs in your screen
   
   banner.loadAd(placementId = YOUR_BANNER_PLACEMENT, listener = object : AdLoadListener {
       override fun onAdLoaded(ad: Ad) {
           // The ad is showing. Nothing else to do — the impression is
           // reported for you once it has been on screen long enough.
       }
       override fun onNoFill() {
           // No ad was available right now. This is normal — just hide the slot.
           banner.visibility = View.GONE
       }
       override fun onError(error: AdError) {
           Log.w("PepAds", "Banner failed: " + error.message)
       }
   })

   A tap on the banner is tracked and opens the advertiser's link automatically. You write none of that.

4. Show a rewarded ad

   A rewarded ad is full-screen and the user watches it to the end. Load it first, then show it when the user chooses to (for example, taps a "Watch to earn" button).

   KotlinCopy

   val rewarded = RewardedAd(placementId = YOUR_REWARDED_PLACEMENT)
   
   rewarded.load(object : AdLoadListener {
       override fun onAdLoaded(ad: Ad) {
           // Loaded and ready. Show it (you need the current Activity).
           rewarded.show(activity, object : RewardedAdListener {
               override fun onRewardEarned(trackingToken: String) {
                   // The user finished watching the ad.
               }
               override fun onDismissed(completed: Boolean) {
                   // The dialog closed. `completed` is true if it was watched to the end.
               }
               override fun onError(error: AdError) { }
           })
       }
       override fun onNoFill() {
           // No rewarded ad available right now — tell the user to try later.
       }
       override fun onError(error: AdError) { }
   })

Java note

Every class here works from Java too, unchanged — see the Android · Java tab for the same steps in Java syntax.

Troubleshooting

• Always "no fill"? Check your placement id is correct and active, and that ads are running for your app.
• Testing against a local server? Android blocks plain http:// by default. Add android:usesCleartextTraffic="true" to your debug manifest, and pass the base URL as the third argument: PepAds.init(YOUR_APP_KEY, YOUR_APP_SECRET, "http://10.0.2.2:PORT") (the emulator's address for your computer). Never ship cleartext in a release build.

Android · Java

Before you start: Android Studio, an app with minSdk 24 or higher, and a placement id from PEP. The SDK is the same artifact as Kotlin — it is built to read naturally from Java.

1. Add the SDK to your project

   In settings.gradle, inside dependencyResolutionManagement { repositories { … } }:

   settings.gradleCopy

   maven { url 'https://pepecosystem-com.b-cdn.net/sdk/maven' }

   Then in your app module's build.gradle, inside dependencies { … }:

   app/build.gradleCopy

   implementation 'com.pepecosystem:pepads:0.1.1'

   Click Sync Now.

2. Start the SDK once

   MyApp.javaCopy

   public class MyApp extends Application {
       @Override public void onCreate() {
           super.onCreate();
           // Key and secret: My Apps -> Secrets -> Enable Ads.
           PepAds.init(YOUR_APP_KEY, YOUR_APP_SECRET);
           PepAds.setIdentity(currentPepUserId);   // optional
       }
   }

3. Show a banner

   JavaCopy

   BannerAdView banner = new BannerAdView(context);
   yourLayout.addView(banner);
   
   banner.loadAd(YOUR_BANNER_PLACEMENT, new AdLoadListener() {
       @Override public void onAdLoaded(Ad ad) { }
       @Override public void onNoFill() { banner.setVisibility(View.GONE); }
       @Override public void onError(AdError error) {
           Log.w("PepAds", "Banner failed: " + error.message);
       }
   });

4. Show a rewarded ad

   JavaCopy

   RewardedAd rewarded = new RewardedAd(YOUR_REWARDED_PLACEMENT);
   
   rewarded.load(new AdLoadListener() {
       @Override public void onAdLoaded(Ad ad) {
           rewarded.show(activity, new RewardedAdListener() {
               @Override public void onRewardEarned(String trackingToken) {
                   // The user finished watching the ad.
               }
               @Override public void onDismissed(boolean completed) { }
               @Override public void onError(AdError error) { }
           });
       }
       @Override public void onNoFill() { }
       @Override public void onError(AdError error) { }
   });

Troubleshooting

• Always "no fill"? Confirm the placement id is correct and active.
• Local server testing? Add android:usesCleartextTraffic="true" to your debug manifest and call PepAds.init(YOUR_APP_KEY, YOUR_APP_SECRET, "http://10.0.2.2:PORT").

React Native

Before you start: a React Native app (0.71+), and a placement id from PEP. The package is Android only today — on iOS the components render nothing, so your app still runs but shows no ads there.

1. Install the package

   terminalCopy

   npm install https://pepecosystem-com.b-cdn.net/sdk/npm/pepecosystem-pepads-0.1.1.tgz

   React Native links the native code automatically. You do not need to edit any Java or Kotlin.

2. Point Android at the SDK

   The package uses a small native library that lives on the PEP CDN. Tell Android where to find it: open android/build.gradle and add the repository under allprojects { repositories { … } }:

   android/build.gradleCopy

   maven { url 'https://pepecosystem-com.b-cdn.net/sdk/maven' }

   Rebuild the Android app once (npx react-native run-android) so the native part is picked up.

3. Start the SDK once

   Call PepAds.init() as your app boots — for example, in a top-level useEffect in your App component. Pass the app key and app secret from My Apps → Secrets → Enable Ads. Keep the secret out of your JS bundle where you can — read it from a native config or your build's environment rather than hard-coding it.

   App.jsCopy

   import { useEffect } from 'react';
   import PepAds from '@pepecosystem/pepads';
   
   export default function App() {
     useEffect(() => {
       PepAds.init(YOUR_APP_KEY, YOUR_APP_SECRET);
       PepAds.setIdentity(currentPepUserId);   // optional
     }, []);
   
     // …your app…
   }

   Testing against a local server? Pass the base URL as the third argument: PepAds.init(YOUR_APP_KEY, YOUR_APP_SECRET, 'http://10.0.2.2:PORT').

4. Show a banner

   PepAdsBanner is a normal React Native component. Drop it into your layout and give it a height; the ad fills the width and keeps its own shape.

   JSXCopy

   import { PepAdsBanner } from '@pepecosystem/pepads';
   
   function HomeScreen() {
     return (
       <View>
         <Text>Your content</Text>
   
         <PepAdsBanner
           placementId={YOUR_BANNER_PLACEMENT}
           style={{ height: 90, width: '100%' }}
         />
   
         <Text>More content</Text>
       </View>
     );
   }

   The impression and any tap are tracked for you — no callbacks needed for a basic banner.

5. Show a rewarded ad

   Rewarded ads use promises. Load one, then show it when the user asks. showRewarded resolves once the user has watched it to the end.

   JavaScriptCopy

   import PepAds from '@pepecosystem/pepads';
   
   async function watchToEarn() {
     try {
       const ad = await PepAds.loadRewarded(YOUR_REWARDED_PLACEMENT);
       if (!ad) {
         // null means no ad was available right now.
         return;
       }
       await PepAds.showRewarded(YOUR_REWARDED_PLACEMENT);
   
       // The user finished watching the ad.
     } catch (e) {
       console.warn('Rewarded failed:', e.message);
     }
   }

   If you also want to know when the ad dialog closes:

   JavaScriptCopy

   const sub = PepAds.onRewardedDismissed(({ completed }) => {
     console.log('closed, watched to end:', completed);
   });
   // later, when you no longer need it:
   sub.remove();

Troubleshooting

• Build fails after install? Make sure you added the maven line in step 2 and did a full run-android rebuild (Metro reload alone is not enough for native changes).
• Banner is invisible? Give it a real height in its style — without one there is no space to draw into.
• Nothing on iOS? Expected — the package is Android only for now.

Flutter

Before you start: a Flutter app on Flutter 3.10 or newer, with Android minSdk 24 or higher (check android/app/build.gradle), and a placement id from PEP. The plugin is Android only today — on iOS every call does nothing and the widgets render nothing, so your app still runs.

1. Add the plugin

   In pubspec.yaml, under dependencies::

   pubspec.yamlCopy

   dependencies:
     pepads: ^0.1.0

   Run flutter pub get.

2. Point Android at the SDK

   The plugin uses a native library on the PEP CDN. Open android/build.gradle and add the repository under allprojects { repositories { … } }:

   android/build.gradleCopy

   maven { url 'https://pepecosystem-com.b-cdn.net/sdk/maven' }

   Then rebuild once with flutter run.

3. Start the SDK once

   Call PepAds.init() as your app starts, for example in main(). Pass the app key and app secret from My Apps → Secrets → Enable Ads. Read the secret from your build config (for example --dart-define) rather than committing it.

   main.dartCopy

   import 'package:flutter/material.dart';
   import 'package:pepads/pepads.dart';
   
   Future<void> main() async {
     WidgetsFlutterBinding.ensureInitialized();
     await PepAds.init(appKey: YOUR_APP_KEY, appSecret: YOUR_APP_SECRET);
     await PepAds.setIdentity(currentPepUserId);   // optional
     runApp(const MyApp());
   }

   Testing against a local server? Add the base URL: PepAds.init(appKey: YOUR_APP_KEY, appSecret: YOUR_APP_SECRET, baseUrl: 'http://10.0.2.2:PORT').

4. Show a banner

   PepAdsBanner is a widget. Place it in your layout and give it a height (wrap it in a SizedBox); the ad fills the width and keeps its shape.

   DartCopy

   Column(
     children: [
       const Text('Your content'),
   
       const SizedBox(
         height: 90,
         child: PepAdsBanner(placementId: YOUR_BANNER_PLACEMENT),
       ),
   
       const Text('More content'),
     ],
   )

   The impression and any tap are tracked for you.

5. Show a rewarded ad

   Rewarded ads use futures. Load one, then show it when the user asks; showRewarded completes once the ad has been watched to the end.

   DartCopy

   Future<void> watchToEarn() async {
     try {
       final ad = await PepAds.loadRewarded(YOUR_REWARDED_PLACEMENT);
       if (ad == null) {
         // No ad available right now.
         return;
       }
       await PepAds.showRewarded(YOUR_REWARDED_PLACEMENT);
   
       // The user finished watching the ad.
     } catch (e) {
       debugPrint('Rewarded failed: $e');
     }
   }

   To know when the ad closes, listen to the stream:

   DartCopy

   final sub = PepAds.onRewardedDismissed.listen((event) {
     debugPrint('closed, watched to end: ${event.completed}');
   });
   // later:  sub.cancel();

Troubleshooting

• Build fails? Confirm the maven line in step 2 and do a full flutter run (hot reload does not rebuild native code).
• Banner not visible? Wrap it in a SizedBox with a height — a widget with no height has nowhere to draw.
• Nothing on iOS? Expected — the plugin is Android only for now.