Docs du SDK

Intégrez le SDK Android d'Appaloo à votre application et diffusez vos annonces en quelques lignes de code.

Installation

Ajoutez le SDK Appaloo à votre projet Android depuis notre dépôt Maven. Le SDK cible Android API 30+.

settings.gradle.kts

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

app/build.gradle.kts

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

Autorisations

Le SDK a besoin d'un accès Internet pour récupérer les médias des annonces.

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

Initialisation

Construisez un AppalooClient avec l'UUID de votre annonce. Si vous intégrez plusieurs annonces, vous pouvez créer un client pour chacune : c'est un objet léger.

import com.appaloo.AppalooClient

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

Annonces interstitielles

Les annonces interstitielles sont des annonces plein écran qui peuvent servir de pause naturelle entre deux écrans, ou d'annonce autonome déclenchée par une action de l'utilisateur.

Les utilisateurs peuvent fermer ces annonces après un compte à rebours de 15 secondes ou, pour les annonces vidéo, à la fin de la vidéo.

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")
			}
		})
	}
}

Annonces récompensées

Les annonces avec récompense sont des annonces vidéo qui récompensent l'utilisateur lorsqu'il les regarde en entier. Elles servent généralement à inciter les utilisateurs à accomplir une action ou à interagir avec l'application.

Même déroulement que loadInterstitial, mais le SDK n'appelle onAdFinished qu'une fois l'annonce entièrement visionnée. Accordez votre récompense dans ce 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)")
			}
		})
	}
}

Important : n'attribuez la récompense qu'à l'intérieur de onAdFinished. onAdLoaded se déclenche dès que l'annonce est affichée, avant que l'utilisateur ne l'ait regardée.

Annonces intégrées

Les annonces intégrées sont de petites annonces qui s'insèrent dans votre propre mise en page. Vous pouvez les utiliser dans un fil d'actualité, un annuaire, une galerie photo, et bien d'autres endroits.

import com.appaloo.AppalooClient
import android.view.ViewGroup

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

	private fun addInlineAd(container: ViewGroup) {
		val adView = appaloo.loadInline(this)
		container.addView(adView)
	}
}

Dans Jetpack Compose, encapsulez-la dans un AndroidView :

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material3.Text
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.compose.ui.viewinterop.AndroidView
import com.appaloo.AdDetails
import com.appaloo.AppalooClient
import com.appaloo.InlineCallbacks

@Composable
fun AppalooInlineAd(modifier: Modifier = Modifier) {
	val appaloo = remember { AppalooClient("{adID}") }

	var hasAd by remember { mutableStateOf(true) }

	if (hasAd) {
		AndroidView(
			modifier = modifier.fillMaxWidth().height(275.dp),

			factory = { ctx ->
				appaloo.loadInline(ctx, object : InlineCallbacks {
					override fun onAdLoaded(adDetails: AdDetails) {}

					override fun onAdLoadFailed(errorCode: Int, message: String) {
						hasAd = false
					}
				})
			},
		)
	}
}

@Composable
fun Feed() {
	LazyColumn {
		item { Text("A post") }
		item { AppalooInlineAd() }
		item { Text("Another post") }
	}
}

Absence d'annonce avec Compose

AndroidView mesure l'annonce à partir des contraintes Compose : la vue ne peut donc pas se réduire à une hauteur nulle lorsqu'aucune annonce n'est disponible. Suivez plutôt l'état de remplissage dans vos callbacks et retirez le composable de l'arbre, comme le fait l'exemple.

Annonces bannière

Les bannières sont un bandeau compact ancré sur toute la largeur. loadBanner renvoie une View que vous placez où vous le souhaitez, généralement ancrée en bas de l'écran. Elle se remplit dès qu'une annonce est diffusée et se réduit à une hauteur nulle si aucune n'est disponible.

import com.appaloo.AppalooClient
import com.appaloo.AdDetails
import com.appaloo.BannerCallbacks
import android.view.ViewGroup

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

	private fun addBanner(container: ViewGroup) {
		val adView = appaloo.loadBanner(this, object : BannerCallbacks {
			override fun onAdLoaded(adDetails: AdDetails) {
				Log.d("Appaloo", "Banner for ${adDetails.appName}")
			}

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

Dans Jetpack Compose, encapsulez-la dans un AndroidView :

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.compose.ui.viewinterop.AndroidView
import com.appaloo.AdDetails
import com.appaloo.AppalooClient
import com.appaloo.BannerCallbacks

@Composable
fun AppalooBannerAd(modifier: Modifier = Modifier) {
	val appaloo = remember { AppalooClient("{adID}") }

	var hasAd by remember { mutableStateOf(true) }
	var hasLoadedAd by remember { mutableStateOf(false) }

	if (hasAd) {
		AndroidView(
			modifier = modifier.fillMaxWidth().height(64.dp),
			factory = { ctx ->
				appaloo.loadBanner(ctx, object : BannerCallbacks {
					override fun onAdLoaded(adDetails: AdDetails) { hasLoadedAd = true }

					override fun onAdLoadFailed(errorCode: Int, message: String) {
						// Keep the current banner if an automatic refresh fails.
						if (!hasLoadedAd) hasAd = false
					}
				})
			},
		)
	}
}

@Composable
fun HomeScreen() {
	Column {
		// your app content
		Spacer(Modifier.weight(1f))
		AppalooBannerAd()
	}
}

Absence d'annonce avec Compose

Annonces à l'ouverture

Les annonces à l'ouverture sont de brèves annonces plein écran adaptées au lancement de l'application ou à son retour au premier plan.

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

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

	override fun onCreate(savedInstanceState: Bundle?) {
		super.onCreate(savedInstanceState)
		setContentView(R.layout.activity_main)

		appaloo.loadAppOpen(this, object : InterstitialCallbacks {
			override fun onAdLoaded(adDetails: AdDetails) {
				Log.d("Appaloo", "App Open ad for ${adDetails.appName}")
			}

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

Sécurité des données

Le SDK ne collecte aucun identifiant publicitaire ni identifiant d'appareil. Les seules données qu'il transmet sont les annonces qu'un utilisateur voit ou sur lesquelles il clique, ce qui garde votre formulaire de sécurité des données Google Play très court.

Ce qu'il faut déclarer

Déclarez les événements d'affichage et de clic sur les annonces sous Activité de l'application (Interactions dans l'application) : collectés, chiffrés en transit et non liés à un identifiant persistant. Choisissez Fonctionnalité de l'application et/ou Publicité comme finalité, selon la façon dont vous décrivez Appaloo.

Ce que le SDK ne collecte pas

Aucun identifiant publicitaire Google (AAID), aucun ANDROID_ID, aucune information sur l'appareil ni aucune localisation. Le SDK ne demande que l'autorisation INTERNET. N'ajoutez pas l'autorisation AD_ID en son nom.

Installation

Le SDK Appaloo est fourni sous forme de XCFramework précompilé, servi directement depuis notre CDN. Il cible iOS 15+ et n'ajoute aucune dépendance.

Xcode (Ajouter un package local)

Déposez ce package Swift d'un seul fichier dans votre projet, puis dans Xcode choisissez File → Add Package Dependencies → Add Local… et sélectionnez le dossier. Xcode télécharge et vérifie le binaire depuis le CDN.

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

Package.swift

Ou, si votre application est elle-même un package Swift, déclarez directement la cible binaire :

targets: [
	.binaryTarget(
		name: "AppalooSDK",
		url: "https://download.appaloo.io/appaloo-sdk/ios/AppalooSDK-1.0.4.xcframework.zip",
		checksum: "3aae03b7fb81068b71c4d45d3c302d32d6668308adb38060ac0498d4c2613ae0"
	),
	.target(name: "MyApp", dependencies: ["AppalooSDK"]),
]

Initialisation

Construisez un AppalooClient avec l'UUID de votre annonce. Si vous intégrez plusieurs annonces, vous pouvez créer un client pour chacune : c'est un objet léger.

import AppalooSDK

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

Annonces interstitielles

Les annonces interstitielles sont des annonces plein écran qui peuvent servir de pause naturelle entre deux écrans, ou d'annonce autonome déclenchée par une action de l'utilisateur.

Les utilisateurs peuvent fermer ces annonces après un compte à rebours de 15 secondes ou, pour les annonces vidéo, à la fin de la vidéo.

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)")
	}
}

InterstitialCallbacks

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

Annonces récompensées

Même déroulement que loadInterstitial, mais le SDK n'appelle onAdFinished qu'une fois l'annonce entièrement visionnée. Accordez votre récompense dans ce callback.

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))")
	}
}

RewardedCallbacks

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

Important : n'attribuez la récompense qu'à l'intérieur de onAdFinished. onAdLoaded se déclenche dès que l'annonce est affichée, avant que l'utilisateur ne l'ait regardée.

Annonces intégrées

import UIKit
import AppalooSDK

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

	private func addInlineAd(to stack: UIStackView) {
		// Returns a 100%-wide, ~275pt-tall card that fills itself in once an ad is
		// served (and collapses if none is available). Tapping it expands the ad.
		let adView = appaloo.loadInline()
		stack.addArrangedSubview(adView)
	}
}

Dans SwiftUI, encapsulez-la dans un UIViewRepresentable :

import SwiftUI
import AppalooSDK

// Wrap the inline view for SwiftUI.
struct AppalooInlineAd: UIViewRepresentable {
	let client: AppalooClient
	func makeUIView(context: Context) -> AppalooInlineAdView { client.loadInline() }
	func updateUIView(_ view: AppalooInlineAdView, context: Context) {}
}

struct FeedView: View {
	let appaloo = AppalooClient(adId: "{adID}")

	var body: some View {
		List {
			Text("A post")
			AppalooInlineAd(client: appaloo).frame(height: 275)
			Text("Another post")
		}
	}
}

Annonces bannière

Les bannières sont un bandeau compact ancré sur toute la largeur. loadBanner renvoie un AppalooBannerAdView que vous placez où vous le souhaitez, généralement ancré en bas de l'écran. Il se remplit dès qu'une annonce est diffusée et se réduit à une hauteur nulle si aucune n'est disponible.

import UIKit
import AppalooSDK

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

	private func addBanner(to container: UIView) {
		let adView = appaloo.loadBanner(callbacks: self)
		adView.translatesAutoresizingMaskIntoConstraints = false
		container.addSubview(adView)
		NSLayoutConstraint.activate([
			adView.leadingAnchor.constraint(equalTo: container.leadingAnchor),
			adView.trailingAnchor.constraint(equalTo: container.trailingAnchor),
			adView.bottomAnchor.constraint(equalTo: container.safeAreaLayoutGuide.bottomAnchor),
		])
	}

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

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

Dans SwiftUI, encapsulez-la dans un UIViewRepresentable :

import SwiftUI
import AppalooSDK

// Wrap the banner view for SwiftUI.
struct AppalooBannerAd: UIViewRepresentable {
	let client: AppalooClient
	func makeUIView(context: Context) -> AppalooBannerAdView { client.loadBanner() }
	func updateUIView(_ view: AppalooBannerAdView, context: Context) {}
}

struct ContentView: View {
	let appaloo = AppalooClient(adId: "{adID}")

	var body: some View {
		VStack {
			Text("My app content")
			Spacer()
			AppalooBannerAd(client: appaloo).frame(height: 64)
		}
	}
}

Annonces à l'ouverture

Les annonces à l'ouverture sont de brèves annonces plein écran adaptées au lancement de l'application ou à son retour au premier plan.

import UIKit
import AppalooSDK

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

	func showAppOpenAd(from presenter: UIViewController) {
		appaloo.loadAppOpen(from: presenter, callbacks: self)
	}

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

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

Sécurité des données

Le SDK ne collecte aucun IDFA ni identifiant d'appareil. Les seules données qu'il transmet sont les annonces qu'un utilisateur voit ou sur lesquelles il clique, et comme il ne porte aucun identifiant inter-applications, il ne nécessite pas d'invite App Tracking Transparency.

Étiquette de confidentialité de l'app

Déclarez les Données publicitaires sous Données non liées à vous, marquées Non utilisées pour le suivi. C'est tout ce que le SDK transmet.

Manifeste de confidentialité inclus

Le XCFramework inclut déjà un PrivacyInfo.xcprivacy qui déclare exactement cela. Xcode l'agrège au rapport de confidentialité de votre application au moment de la compilation, vous n'avez donc rien à ajouter vous-même.