SDK Docs

Drop the Appaloo Android SDK into your app and serve your ads with a few lines of code.

1. Installation

Add the Appaloo SDK to your Android project from our Maven repository. It ships as a prebuilt AAR and targets Android API 30+.

settings.gradle.kts

dependencyResolutionManagement {
	repositories {
		google()
		mavenCentral()
		maven { url = uri("https://static.appaloo.io/appaloo/sdk/android") }
	}
}

app/build.gradle.kts

dependencies {
	implementation("io.appaloo:sdk:0.0.1")
}

Permissions

The SDK needs internet access to fetch ad manifests and media. Add the following to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

2. Initialization

Construct an AppalooClient with your ad's UUID. The client is cheap to create. Instantiate one per call site, or hold one as a field on your activity.

import com.appaloo.AppalooClient

private val appaloo = AppalooClient(
	adId = "{adID}",
)

3. Loading an Ad

Use loadInterstitial for interstitial ads and loadRewarded for rewarded ads. Calling the wrong method for an ad's type fails with ERROR_NOT_INTERSTITIAL or ERROR_NOT_REWARDED.

Interstitial Ads

Fetches the manifest, picks a candidate, and presents a fullscreen interstitial dialog. The user can dismiss it after a 15-second countdown (or after the embedded video ends).

import com.appaloo.AppalooClient
import com.appaloo.AdDetails
import com.appaloo.InterstitialCallbacks

class MainActivity : AppCompatActivity() {
	private val appaloo = AppalooClient("{adID}")

	private fun showAd() {
		appaloo.loadInterstitial(this, object : InterstitialCallbacks {
			override fun onAdLoaded(adDetails: AdDetails) {
				Log.d("Appaloo", "Showing ad for ${adDetails.appName}")
			}

			override fun onAdLoadFailed(errorCode: Int, message: String) {
				Log.w("Appaloo", "Ad failed: $errorCode - $message")
			}
		})
	}
}

Rewarded Ads

Same flow as loadInterstitial, but the SDK invokes onAdFinished only after the user has fully viewed the ad. Gate your reward on this callback.

import com.appaloo.AppalooClient
import com.appaloo.AdDetails
import com.appaloo.RewardedCallbacks

class GameActivity : AppCompatActivity() {
	private val appaloo = AppalooClient("{adID}")

	private fun grantBonusLife() {
		appaloo.loadRewarded(this, object : RewardedCallbacks {
			override fun onAdLoaded(adDetails: AdDetails) {
				// Ad is on screen; do not credit yet.
			}

			override fun onAdFinished(adDetails: AdDetails) {
				// User finished watching: credit the reward here.
				player.lives += 1
			}

			override fun onAdLoadFailed(errorCode: Int, message: String) {
				Log.w("Appaloo", "Reward unavailable ($errorCode)")
			}
		})
	}
}

4. Callbacks

All callbacks are dispatched on the main thread, so you can update UI directly from inside them.

InterstitialCallbacks

interface InterstitialCallbacks {
	fun onAdLoaded(adDetails: AdDetails)
	fun onAdLoadFailed(errorCode: Int, message: String)
}

RewardedCallbacks

interface RewardedCallbacks {
	fun onAdLoaded(adDetails: AdDetails)
	fun onAdFinished(adDetails: AdDetails)
	fun onAdLoadFailed(errorCode: Int, message: String)
}

Important: only credit the reward inside onAdFinished. onAdLoaded fires as soon as the ad is rendered, before the user has watched it.

5. Data Safety

The SDK collects no advertising ID and no device identifiers. The only data it reports is which ads a user views or clicks, which keeps your Google Play Data Safety form short.

What to declare

Declare ad view and click events under App activity (App interactions): collected, encrypted in transit, and not linked to a persistent identifier. Pick App functionality and/or Advertising as the purpose to match how you describe Appaloo.

What the SDK does not collect

No Google Advertising ID (AAID), no ANDROID_ID, no device info, and no location. The SDK requests only the INTERNET permission. Do not add the AD_ID permission on its behalf.

Install attribution

On first launch the SDK reports a one-time install-referrer click ID (Appaloo's own click UUID, not a Google or device ID) so cross-promotion installs can be credited. It is covered by the same App interactions declaration.

1. Installation

The Appaloo SDK ships as a prebuilt, checksum-pinned XCFramework served straight from our CDN. Nothing to compile, no account, no token, no git host. It targets iOS 15+ and depends only on system frameworks (UIKit, WebKit).

Xcode (Add Local package)

Drop this one-file Swift package into your project, then in Xcode choose File → Add Package Dependencies → Add Local… and select the folder. Xcode downloads and verifies the binary from the CDN.

mkdir AppalooSDK && curl -fsSL \
  https://static.appaloo.io/appaloo/sdk/ios/AppalooSDK/Package.swift \
  -o AppalooSDK/Package.swift

Package.swift

Or, if your app is itself a Swift package, declare the binary target directly:

targets: [
	.binaryTarget(
		name: "AppalooSDK",
		url: "https://appaloo.nyc3.digitaloceanspaces.com/appaloo/sdk/ios/AppalooSDK-0.1.1.xcframework.zip",
		checksum: "e0dc8f262263d079b6cb21bd8d4e958407fc9e749fcb6cb0e8ec192afb334a84"
	),
	.target(name: "MyApp", dependencies: ["AppalooSDK"]),
]

2. Initialization

Construct an AppalooClient with your ad's UUID. While the client is light on resources, it is better practice to keep a long living reference to one as a property on your view controller.

import AppalooSDK

private let appaloo = AppalooClient(adId: "{adID}")

3. Loading an Ad

Use loadInterstitial for interstitial ads and loadRewarded for rewarded ads. Calling the wrong method for an ad's type fails with errorNotInterstitial or errorNotRewarded.

Both load methods take a presenting UIViewController and the SDK presents the ad fullscreen on top of it (modalPresentationStyle = .fullScreen, isModalInPresentation = true).

Interstitial Ads

Presents an ad to the user. The user can dismiss it after a 15 second countdown (or after an embedded video ends).

import UIKit
import AppalooSDK

final class MainViewController: UIViewController, InterstitialCallbacks {
	private let appaloo = AppalooClient(adId: "{adID}")

	private func showAd() {
		appaloo.loadInterstitial(from: self, callbacks: self)
	}

	func onAdLoaded(adDetails: AdDetails) {
		print("Showing ad for \(adDetails.appName)")
	}

	func onAdLoadFailed(errorCode: Int, message: String) {
		print("Ad failed: \(errorCode) - \(message)")
	}
}

Rewarded Ads

Same flow as loadInterstitial, but onAdFinished only fires after the user has fully viewed the ad. You should then credit the reward to the user.

import UIKit
import AppalooSDK

final class GameViewController: UIViewController, RewardedCallbacks {
	private let appaloo = AppalooClient(adId: "{adID}")

	private func grantBonusLife() {
		appaloo.loadRewarded(from: self, callbacks: self)
	}

	func onAdLoaded(adDetails: AdDetails) {
		// Ad is on screen; do not credit yet.
	}

	func onAdFinished(adDetails: AdDetails) {
		// User finished watching: credit the reward here.
		player.lives += 1
	}

	func onAdLoadFailed(errorCode: Int, message: String) {
		print("Reward unavailable (\(errorCode))")
	}
}

4. Callbacks

Callbacks are class-only protocols (AnyObject). The SDK retains your callbacks object only for the duration of the load. Keep your own strong reference (e.g. as a stored property) until at least onAdFinished or onAdLoadFailed fires. All callbacks are invoked on the main thread.

InterstitialCallbacks

public protocol InterstitialCallbacks: AnyObject {
	func onAdLoaded(adDetails: AdDetails)
	func onAdLoadFailed(errorCode: Int, message: String)
}

RewardedCallbacks

public protocol RewardedCallbacks: AnyObject {
	func onAdLoaded(adDetails: AdDetails)
	func onAdFinished(adDetails: AdDetails)
	func onAdLoadFailed(errorCode: Int, message: String)
}

Important: only credit the reward inside onAdFinished. onAdLoaded fires as soon as the ad is rendered, before the user has watched it.

5. Data Safety

The SDK collects no IDFA and no device identifiers. The only data it reports is which ads a user views or clicks, and because it carries no cross-app identifier it does not require an App Tracking Transparency prompt.

App Privacy nutrition label

Declare Advertising Data under Data Not Linked to You, marked Not Used for Tracking. That is the full extent of what the SDK reports.

Privacy manifest included

The XCFramework already bundles a PrivacyInfo.xcprivacy that declares exactly this. Xcode aggregates it into your app's privacy report at build time, so you do not need to add anything yourself.