Mobile SDK

Platform	Repository	Distribution
Android	Clickonometrics/reporting-sdk-android	Maven Central
iOS	Clickonometrics/reporting-sdk-ios	CocoaPods, Swift Package Manager
Flutter	Clickonometrics/reporting-sdk-flutter	sample application only — see below

The MageAds mobile SDK reports user activity from your application. It is a reporting library: it sends e-commerce events that feed retargeting and audience segments. It does not fetch or display ads — that is a separate integration, described in Serving Ads in an App.

The events themselves — what each one means and when it fires — are described in Tracking & Events. This page covers installing the SDK, wiring it to your screens, and the platform constraints you need to plan for.

Which events to send, and from where

The SDK exposes one call per event. Wire them to the screens that already exist in your app:

Screen or action	Call	Notes
App start	homepageVisitedEvent	Send first — it carries device and app context
Category / listing opened	browsedCategoryEvent	Pass the products visible in the listing
Product detail opened	productBrowsedEvent
Added to cart	productAddedEvent
Removed from cart	productRemovedEvent
Cart opened	cartEvent	Pass the full cart contents
Checkout started	orderStartedEvent
Order completed	productsOrderedEvent	Pass your order identifier — it attributes the sale

Product identifiers must match the identifiers in your MageAds product feed. If the feed uses GTINs and the app sends internal database IDs, events are accepted but never match a campaign.

Quantities and prices must be greater than zero — a quantity of 0 is rejected exactly like a missing value.

Android

Install

dependencies {
    implementation("io.github.clickonometrics.android:clickonometrics:1.1.1")
}

android {
    defaultConfig {
        minSdk = 24   // required
    }
}

The SDK declares AD_ID, INTERNET and ACCESS_NETWORK_STATE itself; they are merged into your manifest. Location is collected only if you request the permission yourself.

Configure

Configure once, as early as possible — events sent before configuration completes are dropped silently, with no error.

EuvicMobileSDK.configure(
    context = applicationContext,
    url = "https://delivery.mageads.com/tracker=multi/track/multi/track.json",
    apiKey = "YOUR_TRACKER_KEY",
    currency = "PLN",
    allowSensitiveData = true
)

Parameter	Required	Notes
url	✅	Tracking endpoint, supplied by MageAds
apiKey	✅	Your tracker key, not the ads API key
userId	—	Overwritten by the AAID whenever one is available
currency	—	Fallback for products without their own currency. Default EUR
allowSensitiveData	—	false disables location, IP and installed-app collection

Send events

EuvicMobileSDK.homepageVisitedEvent()

EuvicMobileSDK.browsedCategoryEvent(
    name = "Buty",
    products = listOf(Product(id = "5901234567890", price = "100.00", currency = "PLN", quantity = 1))
)

EuvicMobileSDK.productsOrderedEvent(
    orderId = "9998",
    saleValue = "300.00",
    products = listOf(/* … */),
    currency = "PLN"
)

Every event accepts an optional trailing block of custom key/value pairs, which is passed through to reporting.

iOS

Install

pod 'EuvicMobileSDK', '~> 1.0'

Swift Package Manager works too, pointing at the same repository:

.package(url: "https://github.com/Clickonometrics/reporting-sdk-ios.git", .upToNextMajor(from: "1.0.0"))

Ask for consent first

The IDFA is unavailable until the user accepts App Tracking Transparency. Add NSUserTrackingUsageDescription to Info.plist and request authorization before the first event:

ATTrackingManager.requestTrackingAuthorization { _ in }

Skip this and the SDK still works — it simply reports every event against an empty identifier, so no profile is ever built. Nothing in the app or the API signals the problem.

Configure and send

import EuvicMobileSDK

EuvicMobile.shared.configure(
    url: "https://delivery.mageads.com/tracker=multi/track/multi/track.json",
    apiKey: "YOUR_TRACKER_KEY"
)

EuvicMobile.shared.homepageVisitedEvent()

let product = EuvicMobileProduct(id: "5901234567890", price: "100.00", currency: "PLN", quantity: 1)
EuvicMobile.shared.productBrowsedEvent(product: product)

Platform support

The SDKs are distributed as prebuilt binaries released in 2022. They remain usable on current toolchains — this table records what has been verified, not what the packages claim.

	Android	iOS
Artifact	AAR clickonometrics:1.1.1	EuvicMobileSDK.xcframework 1.1.0
Minimum OS	Android 7.0 (API 24)	iOS 13
Built with	AGP 7.3, Kotlin 1.7	Swift 5.7.1, Xcode 14.1
Dependencies	OkHttp, Gson, appcompat, play-services-ads-identifier	none beyond system frameworks
Current toolchain	✅ verified against AGP 9.0.1 / Kotlin 2.3.20 / Gradle 9.1 / JDK 17	✅ built with library evolution, loads under Xcode 16 / Swift 6
Current OS	✅ verified on Android 15 (API 35), all eight events accepted	arm64 simulator slice present

The Android artifact is a compiled AAR, not source, so Kotlin language changes do not affect it — it is linked, never recompiled. That is why a 2022 binary still works with Kotlin 2.3.

Constraints to plan for

• minSdk must be raised to 24. Frameworks that default lower — Flutter among them — will not build until you set it explicitly.
• iOS has no privacy manifest. The binary ships without PrivacyInfo.xcprivacy, which Apple has required since May 2024 from SDKs that access the IDFA. This can produce App Store Connect warnings. Talk to the MageAds team before submitting an app that embeds it.
• Swift 6 strict concurrency. The shared instance is not Sendable; call it from the main actor.
• Android data collection. With sensitive data enabled the SDK collects coarse location, IP and the list of installed applications. Declare it in Play Console, or turn the flag off.

Flutter, React Native and other cross-platform frameworks

There is no supported plugin. The published Flutter repository is a 2022 sample application, not a package — it cannot be installed with flutter pub add.

Two approaches work:

A thin platform bridge. Expose the native SDKs through a method channel and call them from shared code. You keep the SDK's behaviour: identifier handling, device context, retries.

Your own implementation. The transport is a single form POST carrying a JSON payload — roughly a hundred lines in any language. You take over reading the advertising identifier and assembling the device context. This avoids the closed binaries entirely and is the cleaner path on iOS, where the missing privacy manifest is a release concern. The payload format is documented in Tracking & Events.

Initialise before the first screen

Configuration is asynchronous on every platform. If your first screen fires its event before configuration finishes, that event is dropped without an error — and on a bridge, a binding that is not yet ready can drop every event while the app looks perfectly healthy. Make sure event calls wait for configuration to complete.

Verifying the integration

1. Watch the responses during development. Accepted events return 200; rejections return 404 and are otherwise invisible. Log them while integrating.
2. Check the identifier. Confirm the identifier leaving the device matches the device's real advertising ID. On an Android emulator the SDK logs its payload under the EuvicMobileSDK tag.
3. Walk the whole funnel. Home → category → product → add to cart → cart → checkout → order. All eight events should fire, in that order.
4. Ask MageAds to confirm. Events that arrive with a valid identifier create an audience profile; the MageAds team can confirm it was created from your app.

If some events succeed and others fail, the cause is usually that a tracker has not been configured for that event type — a key maps to one tracker per event type. Ask MageAds which types your key covers before debugging the app.