Install the mobile SDK (iOS, Android, Flutter)
Install the WebmasterID SDKs for iOS, Android and Flutter from public package channels, start them with the user's consent decision and verify the first event.
Last updated: 2026-10-20
This guide takes a customer from nothing to the first event on the dashboard, on iOS and Android. The main path is Flutter; native Swift (Swift Package Manager) and native Kotlin or Java (Gradle) follow in their own sections. The Flutter quick start is the same text an app's card in the dashboard shows; it and the example app are built from the public packages in a fresh project and run — on an Android emulator and on an iOS Simulator — against a real WebmasterID ingest, including the cases that must send nothing. Other frameworks (React Native, Unity, .NET) are not supported. What the Apps reports show, and what they cannot answer, is on the mobile app analytics page.
1. Prerequisites
- A WebmasterID workspace with service access: an active Pro ($49/month), Agency ($149/month) or Business plan, or a legacy Free account (created before 2026-10-07, 14:21 UTC). Without it the dashboard will not register an app, and the service answers 403 to its events. Plans:
https://dashboard.webmasterid.com/settings/billing. - No GitHub access of any kind. The SDKs install from public channels: the Flutter package from pub.dev, the iOS frameworks from a public Swift package, the Android libraries from a public Maven repository. No account, token, deploy key or private repository is involved, and none must be added to your build.
- Flutter 3.47.0 or newer (Dart 3.13), with Swift Package Manager enabled (it is, by default, since Flutter 3.44). Verified with Flutter 3.47.0 and 3.47.6.
- iOS: Xcode 26.0.1 and 26.6 verified; apps run on iOS 15.0 and newer. The frameworks are built with Xcode 26.0.1 and need no CocoaPods.
- Android: minSdk 24 (Android 7.0), JDK 17, Android Gradle Plugin 8.0 or newer (verified with 8.11.1 (native apps) and 9.1.0 (the Flutter template)). Native Kotlin apps: Kotlin 2.1.21 verified. Native Java apps: Java 17 sources verified.
2. Register the app in the dashboard
- Sign in at
https://dashboard.webmasterid.com. In the sidebar open iOS apps or Android apps. (Registering needs the Owner, Admin or Editor role.) - Fill in Register an app: a display name; the Bundle identifier (iOS, reverse-DNS such as
com.example.app) or the Package name (Android — theapplicationIdof your build); the Environment: Development, TestFlight (iOS only) or Production. The identifier cannot be changed after registration. - Click Register app. The app's card shows Public property ID —
ap_followed by 16 characters — with a Copy button. That is the one value your app needs.
Four different things share these words — keep them apart: the property's environment (Development, TestFlight, Production: which card the events land on, chosen by the id in the build); Apple's purchase environment (Sandbox or Production: decided by the Apple Account that bought — a Sandbox Apple Account or TestFlight is sandbox — and verified per App Store connection); the App Store connection (one per Apple environment, on the app's card, section 6); and the subscriptions switch (a separate deployment-level feature; creating a store connection does not enable it). There is one production dashboard and no test database: a test build sends its ordinary events to whichever property id it was built with, so give test builds their own property; sandbox purchases are verified and never counted either way.
Registering collects nothing. The card reads “SDK not installed — no events have been received for this property” until the first event arrives.
3. Install
Flutter (iOS and Android)
Add the package to pubspec.yaml and run flutter pub get. No Git URL, no path, no dependency override:
# pubspec.yaml — then run: flutter pub get dependencies: webmasterid_flutter: ^0.4.1
- iOS: apps run on iOS 15.0 and newer. A project whose deployment target is lower is raised by
flutter build iositself — it printsUpdating minimum iOS deployment target to 15.0.and rewritesios/Runner.xcodeproj/project.pbxproj; commit that change, and know the app no longer installs below iOS 15.0. The plugin's Swift package depends on the public WebmasterID Swift package by URL, pinned to exactly 1.3.1; Xcode downloads two XCFrameworks and checks their SHA-256. There is no CocoaPods podspec: a project that turned Swift Package Manager off (enable-swift-package-manager: false) must turn it back on. - Android: set
minSdk = 24. The plugin addshttps://webmasterid.com/sdk/mavento your build, restricted to thecom.webmasteridgroup, and pins the Android SDK 0.3.0. If yoursettings.gradle(.kts)usesRepositoriesMode.FAIL_ON_PROJECT_REPOS, add that repository there (the troubleshooting section shows the line). - The example app in section 4 also uses
shared_preferences, to store the person's consent decision:flutter pub add shared_preferencesif you run it. Its completepubspec.yamlis below. If you replace a new project'slib/main.dartwith it, delete the template'stest/widget_test.dart: it tests the template'sMyApp, which no longer exists.
name: webmasterid_consumer
description: A minimal customer app that installs the WebmasterID Flutter SDK exactly as the installation guide says.
publish_to: none
version: 1.0.0+1
environment:
sdk: ^3.13.0
flutter: ">=3.47.0"
dependencies:
flutter:
sdk: flutter
# The WebmasterID SDK, from pub.dev. No Git URL, no path, no override.
webmasterid_flutter: ^0.4.1
# Where this app keeps the consent decision between launches.
shared_preferences: ^2.3.0
dev_dependencies:
flutter_test:
sdk: flutter
flutter_lints: ^6.0.0
flutter:
uses-material-design: true
Native iOS — Swift Package Manager
Xcode: File → Add Package Dependencies…, paste https://github.com/PetroTitan/webmasterid-mobile-sdk.git, choose version 1.3.1, and add the WebmasterID product to your app target — WebmasterIDStoreKit only if your app sells something. In a Package.swift:
dependencies: [
.package(
url: "https://github.com/PetroTitan/webmasterid-mobile-sdk.git",
from: "1.3.1"
)
],
targets: [
.target(
name: "MyApp",
dependencies: [
.product(
name: "WebmasterID",
package: "webmasterid-mobile-sdk"
)
]
)
]Native Android — Gradle (Kotlin or Java)
The repository, in settings.gradle.kts:
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url = uri("https://webmasterid.com/sdk/maven") }
}
}The dependency, in app/build.gradle.kts:
// app/build.gradle.kts
dependencies {
implementation("com.webmasterid:webmasterid-android:0.3.0")
}The same in Groovy (settings.gradle / app/build.gradle):
// settings.gradle
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url 'https://webmasterid.com/sdk/maven' }
}
}// app/build.gradle
dependencies {
implementation 'com.webmasterid:webmasterid-android:0.3.0'
}The library merges exactly one permission into your manifest, INTERNET. Its only external dependency is the Kotlin standard library.
4. Flutter quick start (iOS and Android)
Four different things — keep them apart when something does not work:
- Installation: the package resolves and the app builds. It says nothing about what happens at runtime.
- Initialization:
WebmasterID.initializereturned a client. Nothing has been collected yet. - Instrumentation: your app calls
screenView,ctaTaportrack. Each only queues an event on the device — and only under a consent decision that permits collection. - Delivery: the queue is sent and the server answers. The SDK does it on its own, on iOS and Android alike, about 5 seconds after an event (when events leave the device).
The steps — the same text, in the same order, as the Flutter snippets on your app's card in the dashboard, where they carry your own id. They go where your app starts (after WidgetsFlutterBinding.ensureInitialized()), except consent, which goes where the person decides:
- At every launch, start the client with the decision your app stored —
nulluntil the person decides:// At every launch, once. The id is PUBLIC — it ships inside your app and // authenticates nothing — but it decides where events go, so the build // sets it, one property per platform and environment, with no fallback: // --dart-define=WMID_APP_PROPERTY_ID=ap_YOUR_PROPERTY_ID // Debug and staging builds pass a separate test property. const appPropertyId = String.fromEnvironment('WMID_APP_PROPERTY_ID'); if (!RegExp(r'^ap_[0-9a-z]{16}$').hasMatch(appPropertyId) || appPropertyId == 'ap_xxxxxxxxxxxxxxxx') { throw StateError('Build with --dart-define=WMID_APP_PROPERTY_ID=<the Public property ID>'); } // storedConsent is the decision the person made earlier, as YOUR app stored // it — null until they decide, and nothing is collected before that. final sdk = await WebmasterID.initialize( appPropertyId: appPropertyId, consent: storedConsent, purchases: false, // analytics only; see the guide before selling anything ); - Register the lifecycle observer, once. It records
app_openeach time the app returns to the foreground; delivery does not depend on it:// ONCE per process — an observer added again (say, by a screen that is // rebuilt) records every app_open twice. It records app_open on each // return to the foreground; delivery does not depend on it. final lifecycle = WebmasterIDLifecycleObserver( sdk, onError: (error, _) => debugPrint('WebmasterID lifecycle: ${error.runtimeType}'), ); WidgetsBinding.instance.addObserver(lifecycle); // If whatever holds `sdk` is disposed: WidgetsBinding.instance.removeObserver(lifecycle); - Apply the person's decision when they make it, and store it for the next launch:
// When the person decides, in your own consent flow — never assumed, never // read from App Tracking Transparency. Store it; pass it to initialize at launch. await sdk.setConsent(WebmasterIDConsent.analyticsAllowed); // or .restricted / .disabled
- Only if your app has sign-in: identify after login and when a session is restored; reset on sign-out. Analytics needs neither:
// Only if your app has sign-in. Your own opaque account key — never an e-mail. // Call it after login AND when a session is restored at launch: Future<void> onSignedIn(String accountKey) => sdk.identify(accountKey); // On logout or an account switch — not at every launch: Future<void> onSignedOut() => sdk.resetIdentity();
- Record events — screens, taps, or one of the 14 event names through
track:// Queued on the device; the SDK sends them together about 5 s after the // first, retries on its own, and sends what is left when the app goes to // the background or starts again. No flush() after events. await sdk.screenView('BookingDetail'); await sdk.ctaTap(cta: 'book_now', screen: 'BookingDetail'); - Check the first delivery, once, in a debug build that reports to a test property — then delete the check. It sends nothing itself: ten seconds after the events, expect
queuedEvents=0,acknowledgedat least 1 andstatus=success:// Once, in a debug build that reports to a test property — then delete it; // it is not part of your app. Ten seconds later expect queuedEvents 0, // acknowledged ≥ 1 and status success (a hold other than none says what // delivery is waiting for). Future<void>.delayed(const Duration(seconds: 10), () async { final d = await sdk.diagnostics(); debugPrint('WebmasterID consent=${d?.consent?.name} queuedEvents=${d?.queuedEvents} ' 'attempted=${d?.attempted} acknowledged=${d?.acknowledged} ' 'status=${d?.lastStatusCategory} hold=${d?.deliveryHold} retry=${d?.retryState}'); });
The property id, at build time
The quick start takes the id from the build: --dart-define=WMID_APP_PROPERTY_ID=ap_… on flutter run and on every flutter build that ships (section 7 shows Codemagic); your app's card prints the line with its own id. Give each platform its own property and each environment its own id: the server files an event under the property its id names, whatever device sent it, so a debug build that reports into the production property mixes test events into live data. Built without the id — or with a placeholder, or anything that is not a Public property ID — the quick start and the example app stop at start with a StateError, before the SDK is touched and before any request. There is no default id on purpose: an id-shaped default builds, starts and sends to no property, and the server answers every unknown id with the same 403.
The example app
These steps in a complete lib/main.dart — the app this guide is checked with. It restores consent from its own store, starts the client, registers the lifecycle observer once and removes it on dispose, and restores a demo session. Its Send test event button is the first-event check: the diagnostics at once and ten seconds later, with no flush(). Deliver now calls flush() — a boundary of your choosing, shown once:
// A minimal customer app for the WebmasterID Flutter SDK.
//
// It does, in this order, what the installation guide says every app must do
// at launch: check the build's property id, restore the consent decision,
// start the SDK with it, register the lifecycle observer once, restore the
// app's own session (only if the app has sign-in), and only then send events.
// Its "Send test event" button is the first-event check: one screen view, one
// tap, and the diagnostics at once and ten seconds later — no flush(): the
// SDK delivers on its own. "Deliver now" is flush(), for a boundary you choose.
//
// Dependencies (pubspec.yaml): webmasterid_flutter, and shared_preferences —
// which only THIS example uses, to store the consent decision and the demo
// session. Your app keeps both wherever it already keeps such things.
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'package:webmasterid_flutter/webmasterid_flutter.dart';
/// The app property's PUBLIC id, from the dashboard (iOS apps / Android apps),
/// given at build time: --dart-define=WMID_APP_PROPERTY_ID=ap_…
/// It ships inside the app and addresses your property; it is not a secret and
/// it authenticates nothing. Never put a WebmasterID server key in an app.
///
/// There is deliberately NO default. A default that looks like an id builds,
/// starts and sends — to no property — and the server answers every unknown id
/// with the same 403, so nothing would say why nothing arrives.
const String appPropertyId = String.fromEnvironment('WMID_APP_PROPERTY_ID');
/// The placeholder earlier versions of the installation guide printed.
const String guidePlaceholderPropertyId = 'ap_xxxxxxxxxxxxxxxx';
/// The id this build will use — or a StateError when it is missing, still a
/// placeholder, or not a public property id. It runs before the SDK is touched,
/// so a misconfigured build fails here, on the device, and sends nothing.
/// The message never repeats the value: whatever was configured by mistake
/// stays out of logs.
String requireAppPropertyId(String value) {
if (value.isEmpty) {
throw StateError(
'WMID_APP_PROPERTY_ID is not set. Build with '
'--dart-define=WMID_APP_PROPERTY_ID=<the Public property ID from the dashboard>.',
);
}
if (value == guidePlaceholderPropertyId) {
throw StateError(
"WMID_APP_PROPERTY_ID is still the guide's placeholder. Use the Public "
"property ID shown on your app's card in the dashboard.",
);
}
if (!RegExp(r'^ap_[0-9a-z]{16}$').hasMatch(value)) {
throw StateError(
'WMID_APP_PROPERTY_ID is not a public property id: "ap_" followed by '
'16 lowercase letters or digits, as shown in the dashboard.',
);
}
return value;
}
/// Leave empty for production. Set only for an acceptance run against an
/// endpoint WebmasterID gave you for testing (https://host[:port]).
const String endpoint = String.fromEnvironment('WMID_ENDPOINT');
/// Where this app keeps the person's consent decision between launches. The
/// SDK never stores it: an app restores the decision at every launch.
class ConsentStore {
static const _key = 'webmasterid.consent';
Future<WebmasterIDConsent?> load() async {
final prefs = await SharedPreferences.getInstance();
final name = prefs.getString(_key);
if (name == null) return null;
for (final consent in WebmasterIDConsent.values) {
if (consent.name == name) return consent;
}
return null;
}
Future<void> save(WebmasterIDConsent consent) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString(_key, consent.name);
}
}
/// The app's own notion of who is signed in: an opaque account key, or null.
/// A real app restores this from its auth layer; this one keeps it locally.
class Session {
static const _key = 'app.accountKey';
Future<String?> restore() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getString(_key);
}
Future<void> signIn(String accountKey) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString(_key, accountKey);
}
Future<void> signOut() async {
final prefs = await SharedPreferences.getInstance();
await prefs.remove(_key);
}
}
final consentStore = ConsentStore();
final session = Session();
/// The launch order. Everything the SDK needs happens here, once per process.
Future<WebmasterID> startWebmasterID() async {
// 0. The build's property id — refused here, before the SDK, when it is wrong.
final propertyId = requireAppPropertyId(appPropertyId);
// 1. The decision this app stored — null if the person has not decided yet.
final WebmasterIDConsent? consent = await consentStore.load();
// 2. One client, started with that decision. Analytics only: no purchase
// collector is created, so no store framework is involved at runtime.
final webmasterID = await WebmasterID.initialize(
appPropertyId: propertyId,
consent: consent,
purchases: false,
endpoint: endpoint.isEmpty ? null : Uri.parse(endpoint),
);
// 3. Only if your app has sign-in: YOUR session, restored the way your app
// restores it. An app without accounts leaves out steps 3 and 4; its
// events carry no user, and nothing else changes.
final accountKey = await session.restore();
// 4. Confirm who it is — or end the session an earlier launch left behind.
if (accountKey != null) {
try {
await webmasterID.identify(accountKey);
} on PlatformException catch (e) {
// iOS before the device's first unlock: the Keychain is not reachable,
// nothing was registered — identify again later. Anything else is real.
if (e.code != 'keychain_unavailable') rethrow;
}
} else if ((await webmasterID.diagnostics())?.deliveryHold ==
'identityNotRestored') {
await webmasterID.resetIdentity();
}
return webmasterID;
}
void main() {
WidgetsFlutterBinding.ensureInitialized();
runApp(const ConsumerApp());
}
class ConsumerApp extends StatelessWidget {
const ConsumerApp({super.key});
@override
Widget build(BuildContext context) {
return const MaterialApp(
title: 'WebmasterID consumer',
home: HomeScreen(),
);
}
}
class HomeScreen extends StatefulWidget {
const HomeScreen({super.key});
@override
State<HomeScreen> createState() => _HomeScreenState();
}
class _HomeScreenState extends State<HomeScreen> {
WebmasterID? _webmasterID;
WebmasterIDLifecycleObserver? _lifecycle;
WebmasterIDDiagnostics? _diagnostics;
String? _accountKey;
final List<String> _log = [];
@override
void initState() {
super.initState();
_start();
}
@override
void dispose() {
// The observer was registered by this screen, so it leaves with it. An
// observer registered once for the whole process needs no removal.
final lifecycle = _lifecycle;
if (lifecycle != null) WidgetsBinding.instance.removeObserver(lifecycle);
super.dispose();
}
Future<void> _start() async {
try {
final webmasterID = await startWebmasterID();
if (!mounted) return;
// The lifecycle observer, ONCE for the process: it records app_open each
// time the app comes back to the foreground. Delivery does not depend on
// it — the SDK sends on its own, on iOS and Android: about 5 seconds
// after an event, when the app goes to the background, and after the
// next launch for anything left.
final lifecycle = WebmasterIDLifecycleObserver(
webmasterID,
onError: (error, _) =>
_say('lifecycle observer failed: ${error.runtimeType}'),
);
WidgetsBinding.instance.addObserver(lifecycle);
_lifecycle = lifecycle;
final accountKey = await session.restore();
if (!mounted) return;
setState(() {
_webmasterID = webmasterID;
_accountKey = accountKey;
});
_say('SDK started for $appPropertyId'
'${endpoint.isEmpty ? '' : ' → $endpoint'}');
await _refresh('at start');
} on StateError catch (e) {
// The build's property id (requireAppPropertyId above): the message says
// what to fix and never repeats the configured value.
_say('start failed: $e');
} on PlatformException catch (e) {
// The native SDK refused — consent_conflict, different_endpoint, …:
// reported by its code, never by the platform's message.
_say('start failed: native ${e.code}');
} on ArgumentError catch (e) {
// WMID_ENDPOINT is not https://host[:port].
_say('start failed: invalid ${e.name ?? 'argument'}');
} catch (e) {
_say('start failed: ${e.runtimeType}');
}
}
Future<void> _setConsent(WebmasterIDConsent consent) async {
final webmasterID = _webmasterID;
if (webmasterID == null) return;
await consentStore.save(consent);
await webmasterID.setConsent(consent);
_say('consent → ${consent.name}');
await _refresh();
}
Future<void> _signIn() async {
final webmasterID = _webmasterID;
if (webmasterID == null) return;
// Your own opaque account key — never an e-mail address, which is refused.
const accountKey = 'demo-account-1';
await session.signIn(accountKey);
try {
await webmasterID.identify(accountKey);
_say('identified as $accountKey');
} on PlatformException catch (e) {
_say('identify refused: ${e.code}');
}
setState(() => _accountKey = accountKey);
await _refresh();
}
Future<void> _signOut() async {
final webmasterID = _webmasterID;
if (webmasterID == null) return;
await session.signOut();
await webmasterID.resetIdentity();
setState(() => _accountKey = null);
_say('signed out — a new identity period');
await _refresh();
}
/// THE FIRST-EVENT CHECK: one screen view and one tap, then the diagnostics
/// at once and ten seconds later. Nothing here sends: the SDK delivers on
/// its own about 5 seconds after the first event. Whether the server took
/// the events is in `acknowledged` and `last status` of the second reading,
/// not in the return values.
Future<void> _sendTestEvent() async {
final webmasterID = _webmasterID;
if (webmasterID == null) return;
final queuedView = await webmasterID.screenView('Home');
final queuedTap =
await webmasterID.ctaTap(cta: 'send_test_event', screen: 'Home');
_say('screen_view queued=$queuedView, cta_tap queued=$queuedTap');
await _refresh('at once');
await Future<void>.delayed(const Duration(seconds: 10));
await _refresh('ten seconds later');
}
/// A BOUNDARY YOU CHOOSE: deliver what is queued now and wait for the
/// server's answer — before a test ends, say. Not needed for delivery, and
/// never after every event: events are sent in batches.
Future<void> _deliverNow() async {
final webmasterID = _webmasterID;
if (webmasterID == null) return;
final delivered = await webmasterID.flush();
_say('flush made progress=$delivered');
await _refresh('after flush');
}
Future<void> _refresh([String stage = 'now']) async {
final webmasterID = _webmasterID;
if (webmasterID == null) return;
final diagnostics = await webmasterID.diagnostics();
if (!mounted) return;
setState(() => _diagnostics = diagnostics);
if (diagnostics != null) {
// One line a log reader can grep for. Categories and counts only.
debugPrint('WMID_CONSUMER diagnostics $stage: '
'consent=${diagnostics.consent?.name} '
'queuedEvents=${diagnostics.queuedEvents} '
'attempted=${diagnostics.attempted} '
'acknowledged=${diagnostics.acknowledged} '
'status=${diagnostics.lastStatusCategory} '
'retry=${diagnostics.retryState} '
'hold=${diagnostics.deliveryHold} '
'identityStorage=${diagnostics.identityStorage}');
}
}
void _say(String line) {
debugPrint('WMID_CONSUMER $line');
if (!mounted) return;
setState(() => _log.insert(0, line));
}
@override
Widget build(BuildContext context) {
final d = _diagnostics;
return Scaffold(
appBar: AppBar(title: const Text('WebmasterID consumer')),
body: ListView(
padding: const EdgeInsets.all(16),
children: [
Text('Property: $appPropertyId'),
Text('Signed in as: ${_accountKey ?? 'nobody'}'),
const SizedBox(height: 12),
const Text('1. Consent (the person decides; the app stores it)'),
Wrap(spacing: 8, children: [
FilledButton(
onPressed: () => _setConsent(WebmasterIDConsent.analyticsAllowed),
child: const Text('Allow analytics'),
),
OutlinedButton(
onPressed: () => _setConsent(WebmasterIDConsent.restricted),
child: const Text('Restricted'),
),
OutlinedButton(
onPressed: () => _setConsent(WebmasterIDConsent.disabled),
child: const Text('Disable'),
),
]),
const SizedBox(height: 12),
const Text('2. Session (only if your app has sign-in)'),
Wrap(spacing: 8, children: [
FilledButton(onPressed: _signIn, child: const Text('Sign in')),
OutlinedButton(onPressed: _signOut, child: const Text('Sign out')),
]),
const SizedBox(height: 12),
const Text('3. Events'),
Wrap(spacing: 8, children: [
FilledButton(
onPressed: _sendTestEvent,
child: const Text('Send test event'),
),
OutlinedButton(
onPressed: _deliverNow,
child: const Text('Deliver now'),
),
]),
const SizedBox(height: 16),
const Text('Diagnostics', style: TextStyle(fontWeight: FontWeight.bold)),
if (d == null)
const Text('not started')
else ...[
Text('consent: ${d.consent?.name ?? 'not decided'}'),
Text('queuedEvents: ${d.queuedEvents} acknowledged: ${d.acknowledged} '
'attempted: ${d.attempted}'),
Text('last status: ${d.lastStatusCategory} '
'delivery hold: ${d.deliveryHold}'),
Text('retry: ${d.retryState}'
'${d.retryInSeconds == null ? '' : ' (after ${d.retryInSeconds!.round()} s)'}'),
Text('identity storage: ${d.identityStorage}'),
],
const SizedBox(height: 16),
const Text('Log', style: TextStyle(fontWeight: FontWeight.bold)),
for (final line in _log) Text(line),
],
),
);
}
}
Run it with your property's id: flutter run --dart-define=WMID_APP_PROPERTY_ID=ap_…, tap Allow analytics, then Send test event. Ten seconds later the Diagnostics read queuedEvents: 0, acknowledged: 2 and last status: success.
What is recorded automatically
- No event, by the SDK alone. It notices the app going to the background and coming back — to deliver, and to start a new session after 30 minutes away — but records no screen, no tap and no
app_openby itself. app_open: recorded byWebmasterIDLifecycleObservereach time the app returns to the foreground, under a decision that permits collection.screen_view: recorded byWebmasterIDNavigatorObserverfor named routes it can name (an unnamed or identifier-like route is dropped and reported toonDropped), or by your ownscreenViewcalls.- Everything else is app-emitted:
ctaTapandtrackwith one of the 14 event names. Purchases are separate (section 6).
Consent, and what ATT is not
- Not decided (the state after
initializewithout a decision): nothing is queued and nothing is sent. The SDK writes one local file — its own identity record, holding a random session id — and nothing else. An event tracked in this state is dropped:trackreturns false, and nothing is released later when the decision arrives — the session id persists across the decision, so a later release would be linkable to the installation the decision identifies. The next releases keep this. To keep the cold-startapp_openand first screens, pass the stored decision toinitialize(consent:)at every launch. - analyticsAllowed: events are sent with a random installation id (created now, per install) and, after
identify, your account key. - restricted: events are sent with a session id only — no installation id, no account key; the stored key is deleted. This is reduced identification, not anonymity: a session id, a country derived by the server from the connection, and exact times remain.
- disabled: nothing is sent; the queue, the installation id and the account key on the device are deleted.
- The SDK never stores the decision. Your app stores it and passes it to
initialize(consent:)at every launch;setConsentchanges it later.
Persistent identifiers, restart, unavailable storage
- Installation id: 128 random bits, per install, created only under analyticsAllowed; deleted under restricted and disabled; replaced by
resetIdentity. It is not the advertising id and not the vendor id — the SDK reads neither. - Session id: random, rotates after 30 minutes of inactivity. Sent in every state that sends.
- Account key: the opaque id your app passes to
identify— never an e-mail address (refused) or anything typed by a person. The server stores it only as a keyed hash. - After a restart, an account key stored by an earlier launch labels nothing until
identifywith the same key confirms it in the new process. Delivery waits for that confirmation for at most 30 seconds from the moment the decision is in force; after the window, events go out without a user, and nothing is bound to them later. So restore your session inside the launch sequence, and callresetIdentityonly when you know nobody is signed in. - Unavailable storage: on iOS,
identifywithout your own token throwskeychain_unavailablebefore the device's first unlock — nothing was registered; call it again later. On both platforms a failed write of the account key is reported in diagnostics (identityStorage), and events then carry no key rather than a guessed one.
App Store privacy details and Google Play Data safety
Both stores ask what your app collects, including through SDKs. This is what the WebmasterID SDKs send and what the server keeps. How you answer depends on your app and on Apple's and Google's own definitions; this section is not legal advice.
- iOS, from the SDKs' privacy manifests. Both frameworks ship a
PrivacyInfo.xcprivacy, so Xcode adds their declarations to your app's privacy report.WebmasterIDdeclares product interaction, device ID (the installation id above, not the advertising or vendor id), user ID (the account key) and coarse location (the country the server derives from the connection).WebmasterIDStoreKit, used only for purchase verification, declares purchase history and user ID. Every type is declared as linked to the user, used for analytics and not for tracking; neither framework declares tracking or tracking domains. - Android, for the Data safety form. Google Play has no SDK manifest, so here is what the Android SDK sends: app interactions (event names, screens, the CTA and filter ids your app passes), a random session id, the installation id and, after
identify, the account key; the app version and build, OS major version and time zone, which the server checks but does not store; and the locale, of which it keeps the language. With Google Play purchase evidence it also sends purchase tokens, which the server checks with Google. The request's default User-Agent header carries the device model; the server does not store it. - On the server, for both platforms. The country is derived from the connection when an event arrives; no IP address or user agent is stored. The installation id and the account key are stored only as keyed hashes. Everything is sent over HTTPS.
Native iOS and Android: the same sequence
Swift — the client, consent, lifecycle, identity and events:
import WebmasterID
// This identifier is PUBLIC. It ships inside your app binary and
// anyone can read it out — it addresses your property, it does not
// authenticate anything. Never put a WebmasterID server secret in
// an app. It decides where events go, so each build configuration
// sets it (Info.plist key WebmasterIDAppPropertyID, from an .xcconfig),
// with no fallback. Release: ap_YOUR_PROPERTY_ID. Debug: a separate test property.
guard let appPropertyID = Bundle.main.object(forInfoDictionaryKey: "WebmasterIDAppPropertyID") as? String,
appPropertyID != "ap_xxxxxxxxxxxxxxxx" else {
preconditionFailure("Set WebmasterIDAppPropertyID to the Public property ID")
}
let client = WebmasterIDClient(
configuration: try WebmasterIDConfiguration( // throws for a malformed id
appPropertyID: appPropertyID,
// At every launch, the decision your app stored — .decided(.analyticsAllowed),
// say. Until the person decides: .notDetermined, and nothing is collected.
consent: .notDetermined
)
)// Nothing is collected, queued or stored until you decide. await client.setConsent(.analyticsAllowed) // events + pseudonymous ids await client.setConsent(.restricted) // events only, no stable ids await client.setConsent(.disabled) // stop AND delete what was kept
// Nothing to forward. The client observes UIKit's foreground and background // notifications itself (it swizzles nothing). Events leave about 5 s after // the first one is queued, when the app goes to the background — best // effort: iOS may suspend the app first — and at the next launch for // anything left. An app that still forwards scenePhase from an earlier // version can delete it; a repeated call joins the delivery in progress.
// After an authenticated login. Pass YOUR opaque account key — // an email address is refused, not hashed. try await client.identify(externalUserID: "<your-account-key>") // On logout or an account switch. await client.resetIdentity()
try await client.track(.screenView, context: .init(screen: "BookingDetail")) try await client.track(.ctaTap, context: .init(screen: "BookingDetail", ctaID: "book_now")) // No flush(): both leave together about 5 s later, and a failed request // is retried on its own. Keep flush() for a boundary you choose.
Kotlin:
// One client per process. Consent starts NotDetermined: nothing is collected yet. val sdk = WebmasterID.initialize(applicationContext, "ap_YOUR_PROPERTY_ID")
// The person's decision. Under RESTRICTED no installation id and no user id are sent. sdk.setConsent(Consent.ANALYTICS_ALLOWED)
// Your own opaque account key — never an email — and the obfuscated id you
// also pass to Google Play Billing (setObfuscatedAccountId).
sdk.identify("acct_9f2b71", GooglePlayAccountId.obfuscated("acct_9f2b71"))
// Logout: queued events for the previous person are delivered with no user.
sdk.resetIdentity()sdk.screenView("BookingDetail")
sdk.ctaTap("BookingDetail", "book_now")
sdk.track(EventName.BOOKING_COMPLETED, EventContext.screen("Confirmation"))Java:
// One client per process. Consent starts NotDetermined: nothing is collected yet. WebmasterID sdk = WebmasterID.initialize(getApplicationContext(), "ap_YOUR_PROPERTY_ID");
sdk.setConsent(Consent.ANALYTICS_ALLOWED);
sdk.identify("acct_9f2b71", GooglePlayAccountId.obfuscated("acct_9f2b71"));
sdk.resetIdentity(); // logoutsdk.screenView("BookingDetail");
sdk.ctaTap("BookingDetail", "book_now");
sdk.track(EventName.BOOKING_COMPLETED, EventContext.builder().screen("Confirmation").build());On Android the SDK fills the app version and build, the OS major version, the locale and the time zone from the device; on iOS your app passes them in the event context if it wants them recorded. Delivery is the SDK's on both platforms: about 5 seconds after an event, when the app goes to the background, and after the next launch for anything left — your app forwards nothing and calls no flush().
When events leave the device
track — and screenView, ctaTap — only queue an event on the device, and only when the consent decision permits collection; under “not decided” and disabled they return false and queue nothing. Queued events stay on the device (up to 7 days, 1000 events, 512 KiB), and the SDK sends them in batches on its own while the app is running, the same way on iOS and Android:
- About 5 seconds after an event. The first event queued starts the wait; events recorded meanwhile go in the same request, and a steady stream of events never pushes the delivery back. One request is in flight at a time.
- When the app goes to the background, at once. The SDK notices the transition itself — Swift and Flutter apps forward nothing; Kotlin and Java:
initializeregisters the activity callbacks. The system gives a backgrounded app a short, unguaranteed moment, and nothing runs after the app is suspended, force-quit or terminated: a request that does not finish leaves its events on the device. - After the next launch, about 5 seconds after the client starts, for anything an earlier launch left — once a consent decision that permits collection is in force.
- After a failure, by itself, on a timer the SDK arms while the app runs: a 5xx or no connection is retried after a random wait that grows with each failure, up to 5 minutes; a 429 no sooner than the server's
Retry-Afterasks, however long that is (bounded only by the 7 days an event is kept). Retries do not give up while events are queued: a phone that was offline delivers at the next retry once the network is back, or when the app goes to the background. A suspended or terminated app runs no timer, so nothing is retried until it runs again; a new launch does not know an earlier launch'sRetry-After, and if that window is still running the server answers its first request with another 429 and the time left. - When your app calls
flush()— not needed for delivery. Use it for a boundary you choose, such as the end of a test; it also skips a retry wait, a 429'sRetry-Afterincluded — inside that window the server may answer 429 again. A call made while a delivery is running does not start a second request. - A 403 (
refused) stops delivery for the rest of the process: later events are still queued, nothing more is attempted — not even byflush()— and the next app process tries again. A 400 (clientError) drops that batch; it is never retried.
Two holds apply on every platform: nothing leaves before a consent decision is in force, and an account key stored by an earlier launch holds delivery for up to 30 seconds until identify or resetIdentity. diagnostics() names the hold in force (deliveryHold).
Before iOS SDK 1.3.0 and webmasterid_flutter 0.4.0, an iOS app sent only on flush() or a background transition, and Android SDKs before 0.3.0 did not send at launch. An app still on those versions keeps that behaviour until it is updated (see updating).
5. Verify the integration
Three different things, in order — do not confuse them:
- The SDK is initialized:
diagnostics()returns an object andconsentshows your decision. This proves nothing about the server. - The server accepted the event:
acknowledgedwent up andlastStatusCategoryissuccess. IfqueuedEventsstays above 0 for more than a few seconds, delivery is waiting:deliveryHoldnames a hold andretryStatea retry — see when events leave the device. Arefusedstatus is a 403: the server does not accept events for that id (unknown, archived, or a workspace without service access — it does not say which). - The event is on the dashboard: reload the app's card under iOS apps or Android apps. It changes from “SDK not installed” to Receiving events, with “Last event: <time, UTC> · Events in the last 30 days: N”. On the Apps page, pick the app in the App filter, or its environment in the Environment filter: the page shows Production until you choose Development or TestFlight.
Property and environment: the id in your app must be the Public property ID on the card you are looking at. Each environment is its own property with its own id and its own card, and an app's events appear only under the property its id names.
What the diagnostics fields mean:
consent— The decision in force: analyticsAllowed, restricted, disabled — or null while nothing has been decided.deliveryHold— Why nothing is leaving the device right now: consentNotDecided (no decision yet), identityNotRestored (an earlier launch stored an account key and the SDK is waiting, at most 30 seconds, for identify or resetIdentity), none.queuedEvents— Events on the device not yet acknowledged by the server — including what earlier launches left, so it can be larger than queued. After a successful delivery: 0. On Android the counts are published from the SDK's own thread: read immediately after a call, they can trail it by a moment.queued— Events queued in this process — a counter that only grows, not the number waiting (that is queuedEvents). If track returned false and this stays 0, the consent decision did not permit collection.attempted— Requests sent in this process. Still 0 several seconds after an event means delivery is held: read deliveryHold.acknowledged— Events the server has accepted in this process. This is the number that means "the server took it".deduplicated— Events the server already held — a retry it recognised, not a loss.permanentlyRejected— Events a 400 dropped. They are not retried; lastStatusCategory says clientError.lastStatusCategory— The last server answer: success; clientError (a 400 — the batch was dropped); refused (a 403 — the property does not accept events; delivery stops for the rest of this process); rateLimited (429); serverError (5xx); transportError (no connection); none (nothing sent yet).retryState / retryInSeconds— After a failed attempt: scheduled, with the wait until the retry the SDK has set (the server's Retry-After, in full, or a random backoff of at most 5 minutes); the SDK retries by itself when it is over, while the app is running and events are queued. stoppedPropertyNotAccepting follows a 403 and lasts for the process.identityStorage— Whether the account key could be stored: notWritten, written, or failed with a category (unavailable, locked, encoding, unknown). After a failure events carry no account key — nothing is guessed.droppedOversized / droppedExpired / droppedForCapacity— Events the SDK gave up on: a single event the server will never take, events older than 7 days, or the queue's capacity (1000 events, 512 KiB).
6. Conversions and purchases
Three different things, kept apart on the dashboard: events — screen views, taps, app opens: activity; conversion events, which your app reports when a business action has succeeded; and verified purchases, which WebmasterID checked with Apple or Google. Only verified purchases carry money. Analytics needs neither of the other two: the example above passes purchases: false and creates no store collector. Add purchases only if your app sells something, and read this section first.
Conversion events: what your app reports
Apps → Conversions counts these events by name, as your app's own claims — no store verified them. Send one only after the action has succeeded, in your app or on your backend, never on the tap that asks for it:
signup— an account was created.login— the person signed in.checkout_started— the person started a purchase, for example your app opened the store's purchase sheet. An intent, never a payment.payment_started— the payment step of your own checkout began. For an App Store or Google Play purchase the store's sheet is that step: sendcheckout_startedand let the verified purchase prove the payment.booking_started,booking_completed— a booking or rental, started, and concluded once your backend accepted it. Not for any other kind of action.cancellation,refund_requested— inside your app, the person ended something they had, or asked for money back. The stores report their own cancellations and refunds with the verified purchase.
Screen views, taps and app opens are not conversions: a tap on “Export” is not an export, and a tap on “Buy” is not a payment. An action outside this list — exporting, signing or converting a document, say — is a goal_completed event with a goal_id you name (document_exported, document_signed: letters, digits, _ . -, at most 64 characters), sent after the action succeeded and never on the tap that requested it. Goals are listed on their own table in Conversions, beside the events above and never among them, and carry no money. Do not send such an action under a name that means something else (an export is not a booking_completed). Send goal_completed only with an SDK version that offers it: an older server refuses the whole batch for an unknown name. The call is goalCompleted(goalId:screen:) on Flutter and Android and track(.goalCompleted, context:) with a goalID on iOS — in the next SDK releases (iOS after 1.3.1, Flutter after 0.4.1, Android after 0.3.0); the published versions have no such call.
Funnel stages: declare them, nothing is guessed
The dashboard’s Funnels page (sessions → onboarding → paywall) is built from a stage your app declares for a screen view, out of a closed list in funnel order: launch, onboarding, home, paywall, checkout, result, settings, other. Nothing on the server guesses a stage from a screen name — HomeScreen and pw2 mean nothing to it — and a screen view without a stage is activity that reaches no stage, so an app that declares nothing reads zero at every stage after the first. Declare it where the screen is reported: screenView("Paywall", category: .paywall) on iOS, screenView('Paywall', category: WebmasterIDScreenCategory.paywall) on Flutter — or once, for named routes, with the navigator observer’s categories map or categoryOf — and screenView("Paywall", ScreenCategory.PAYWALL) on Android. The stage travels as screen_category on screen_view only; the server refuses it on any other event and any value outside the list. Like goals, it needs the next SDK releases; the published versions cannot send it.
StoreKit 2 (iOS)
The SDK forwards Apple's signed transaction, unread, to WebmasterID, which verifies it against Apple's certificates. A purchase is attributed to a user only when the appAccountToken Apple signed into the transaction equals the one registered with identify; otherwise the payment is recorded with no user. The SDK never finishes a transaction and never grants an entitlement — both stay your app's. In Swift:
// OPTIONAL. Add this second product only if your app sells something —
// the core never links StoreKit, so an analytics-only app does not
// have to account for it in App Store review.
.product(
name: "WebmasterIDStoreKit",
package: "webmasterid-mobile-sdk"
)import WebmasterIDStoreKit // The collector ATTACHES to the client you already built. Consent and // identity stay owned by that one client — there is no second place to // set them, and no way for the two to disagree about who the user is. let storeKit = try await WebmasterIDStoreKit.attached(to: client) // One Transaction.updates listener. Calling this twice is a no-op. await storeKit.start()
// One random UUID per ACCOUNT, stored with the account — never derived
// from an e-mail or other personal data. The SAME token goes to identify
// and to StoreKit; Apple signs it into the transaction, and only a
// matching signed token lets the purchase be claimed for this user.
try await client.identify(
externalUserID: account.accountKey,
appAccountToken: account.appAccountToken
)
let result = try await product.purchase(
options: [.appAccountToken(account.appAccountToken)]
)
if case let .success(verification) = result {
// Apple's signed transaction, for SERVER-side verification.
await storeKit.submit(verification)
// ⚠ YOU finish the transaction, after granting the entitlement.
// This SDK never calls finish().
if case let .verified(transaction) = verification {
await grantEntitlement(for: transaction)
await transaction.finish()
}
}In Flutter, initialize(purchases: true) (the default) links StoreKit; identify(accountKey, appAccountToken: …) registers the token, which WebmasterIDPurchases.purchaseParam passes to in_app_purchase as applicationUserName, and attach submits the purchased or restored transaction. The package README documents each call.
An enabled App Store connection is required: on the app's card, Sandbox to test (Create URL, then Turn on; no Apple App ID), Production with your numeric Apple App ID. A new connection starts turned off; without an enabled one for the environment of the purchase, WebmasterID refuses every transaction the app sends. The proofs the app hands over do not need the notification URL to be pasted anywhere; that paste only adds Apple's own server notifications.
Google Play Billing (Android)
The SDK carries the purchase token as evidence for the server to verify with Google; it never acknowledges or consumes a purchase and carries no amount. Your app owns the Billing Library, the acknowledgement and the entitlement. The obfuscated account id you give Billing is how a purchase is matched to the identity registered with identify:
dependencies {
implementation("com.webmasterid:webmasterid-googleplay:0.3.0")
}// Attached to the SAME client. Never acknowledges or consumes a purchase, and carries no amount.
val evidence = GooglePlayEvidence.attach(
sdk.client,
GooglePlayEvidence.Configuration(packageName, AndroidStorage.storage(applicationContext, "ap_YOUR_PROPERTY_ID")),
).get()// From your Billing Library PurchasesUpdatedListener: the token is EVIDENCE the
// server verifies with Google. The obfuscated id is read back from the purchase.
evidence.submit(
purchase.purchaseToken,
purchase.products.first(),
GooglePlayProductKind.PRODUCT,
purchase.accountIdentifiers?.obfuscatedAccountId,
)Purchases made with RevenueCat (iOS)
RevenueCat stays the only purchase processor and the only source of access; nothing here moves away from it, and WebmasterID only receives proofs for analytics. Three facts, kept apart:
- Reading RevenueCat's events — not implemented. WebmasterID has no RevenueCat webhook and reads no RevenueCat event. RevenueCat's “Apple Server Notification Forwarding URL” is not used either: whether what it forwards is accepted by WebmasterID's notification route has not been checked, so do not switch it on for WebmasterID.
- Handing Apple's transaction over from the app — in the published SDKs, checked in code. After RevenueCat completes a purchase, the app gives the SDK the App Store transaction id; the SDK finds Apple's own signed transaction on the device and sends that for server-side verification. Nothing RevenueCat-specific is built: it is the same call the Flutter plugin uses beside
in_app_purchase, and no app that combines it with RevenueCat has been compiled in WebmasterID's CI. - Confirmation by a real sandbox purchase — not done. No purchase made through RevenueCat has been carried through Apple's sandbox and verified by WebmasterID. The acceptance test is at the end of this section; until it passed, treat the path as unverified.
Apple posts App Store Server Notifications to one production URL per app and one optional sandbox URL — the ones RevenueCat asked you to set. Do not replace them with WebmasterID's: the Create URL step below produces a URL you leave unused, and the connection's badge then stays “Waiting for Apple's first delivery” by design. No Apple private key, issuer id, .p8 file, shared secret or Apple Account password is involved anywhere in this section, and the notification URL is a credential: keep it out of logs, tickets and screenshots.
The owner, in WebmasterID
- Decide which property the test build reports to. Why: a build sends its events to the property id it was built with, and purchase proofs go to the same property. A separate TestFlight or Development property keeps test events out of production analytics — then the sandbox connection must be created on that property. A test build with the production property id keeps sandbox purchases out of revenue (they never count) but adds its ordinary events to the production reports.
- Create the sandbox connection. Why: without it every sandbox proof is refused. On the app's card (iOS apps, or Settings → App properties), under App Store Server Notifications, Sandbox → Create URL; no Apple App ID is needed for Sandbox. Expected: the card shows the URL once — close it without pasting it anywhere — and the new connection is turned off. On “a connection for this environment already exists”: reload; it is there.
- Turn it on. Turn on on the Sandbox card. Expected: the badge reads “Waiting for Apple's first delivery” and stays so; the app's page (Settings → App properties → the app) shows step 5, Store connection, with a sandbox line. Until this step, a sandbox proof is refused with “no App Store connection was enabled for the environment it named (Sandbox)”.
- Production, later. The same on the Production card, which needs the app's numeric Apple App ID (App Store Connect → App Information → General Information → Apple ID) — not an Apple Account password. Only an enabled production connection accepts production proofs; only production purchases count as revenue. Enabling a connection does not replay historical purchases. A proof still retained in the SDK queue can be retried within its delivery-attempt limit; an abandoned or never-submitted proof is not recovered by turning the connection on. While only the Sandbox connection exists, a production proof is still refused — as “environment mismatch” instead of “no enabled connection” — and still uses one of its attempts.
The developer, in the app
First the versions, in pubspec.lock (or Package.resolved): webmasterid_flutter 0.4.1 (which pins iOS 1.3.1), and which purchases_flutter or RevenueCat iOS SDK version the app uses — the field names below are RevenueCat's and differ between its major versions. Then, in Flutter:
- Keep the purchase collector on:
WebmasterID.initialize(…, purchases: true)— the default; the quick start'spurchases: falseis for apps that sell nothing. With it the plugin links StoreKit and starts its ownTransaction.updateslistener for renewals and purchases made elsewhere; the purchase RevenueCat completes in the app is not guaranteed to reach that listener, which is why the next step exists. - After a successful RevenueCat purchase, hand the transaction id over — after access is granted, never awaited before it, and never as a reason to retry the payment:
// purchases_flutter 9 or later: Purchases.purchase returns a PurchaseResult.
// Older versions (purchasePackage → CustomerInfo) carry no transaction id for a
// subscription; check pubspec.lock before relying on this.
final result = await Purchases.purchase(PurchaseParams.package(package));
grantAccess(result.customerInfo); // RevenueCat's answer, exactly as before
if (Platform.isIOS) {
// Analytics only, NOT awaited (import 'dart:async'): submitTransaction waits
// for the SDK's delivery — a network round trip, longer offline — and the
// purchase screen must not wait for it. The SDK never calls finish().
unawaited(() async {
try {
final outcome = await sdk.storeKit.submitTransaction(
result.storeTransaction.transactionIdentifier,
);
debugPrint('WebmasterID hand-over: $outcome');
} catch (error) {
debugPrint('WebmasterID hand-over failed: ${error.runtimeType}');
}
}());
}submitTransaction answers for the device, not for the server: stored (queued in a protected on-device queue and delivered on its own — right after the call, at the next call or storeKit.flush(), and when the app leaves the foreground with the lifecycle observer registered); alreadyQueued (the same signed transaction is queued already — not an error, nothing goes twice); transactionNotFound (no transaction with that id in this device's App Store history: the id was not the App Store transaction id, or the purchase belongs to another Apple Account); refusedUnverified (StoreKit itself could not vouch for it; nothing is sent); refusedByConsent (the consent decision forbids collection; nothing is written, by design); refusedQueueFull, refusedTooLarge, refusedStorageUnavailable; unsupportedPlatform on Android. It throws if purchases were off at initialize or the id is not numeric. The server's answer arrives later and is visible in storeKit.diagnostics(): lastPaymentOutcome is accepted, duplicate (already received — never counted twice) or rejected (the signature, the bundle id or the environment did not match an enabled connection); pending is what still waits for an acknowledgement. Accepted on the device or by the server is still not “verified”: only the app's page on the dashboard says that.
In Swift (RevenueCat iOS SDK 4 or later), the published SDK has no id-based submit; the app finds Apple's own result and submits that:
import StoreKit
import WebmasterIDStoreKit
// Once, after the client exists. A repeated start() is a no-op.
let storeKit = try await WebmasterIDStoreKit.attached(to: client)
await storeKit.start()
// After RevenueCat completed the purchase (RevenueCat finishes the transaction):
let (transaction, customerInfo, userCancelled) = try await Purchases.shared.purchase(package: package)
grantAccess(from: customerInfo) // RevenueCat's answer, exactly as before
if !userCancelled, let id = transaction?.transactionIdentifier, let appleId = UInt64(id) {
Task.detached { // analytics only, off the purchase's own path
for await result in Transaction.all where result.unsafePayloadValue.id == appleId {
await storeKit.submit(result) // only a .verified result is sent
break
}
}
}Cancelled, pending, restore, duplicate, offline — as the APIs behave: a purchase the person cancelled, or one that is pending (Ask to Buy, SCA), makes Purchases.purchase throw a PlatformException (purchaseCancelledError, paymentPendingError — RevenueCat's codes), so nothing is handed over, which is right: there is no completed transaction. A pending purchase approved later reaches RevenueCat through its own listener and StoreKit through Transaction.updates; whether the SDK's listener sees it before RevenueCat finishes it has not been verified. Purchases.restorePurchases() returns a CustomerInfo and no transaction id, so a restore is not handed over on this path; the server deduplicates on Apple's transaction id anyway, and a transaction it already has answers duplicate — which is also why calling submitTransaction twice for the same id is safe. Offline, stored evidence waits on the device and goes out at the next delivery. A server refusal (HTTP 403, for example “no enabled connection”) is not an acknowledgement either: the SDK keeps the proof and re-sends it at the next delivery, after a back-off and for a bounded number of attempts (maxDeliveryAttempts, 12 by default in the SDK source), then abandons it. Enabling the connection later therefore recovers a refused proof only while the app still holds it, and never one that was never handed over.
Events, and the moment to send them — the published vocabulary; goal_completed and screen_category are not in it (see above):
app_open— byWebmasterIDLifecycleObserver, registered once inmain(), and never tracked by hand as well. In 0.4.1 it fires on every return to the foreground, including the return from the purchase sheet.screen_view—WebmasterIDNavigatorObserverfor named routes, orscreenViewby hand, never both: both report the same screen, and the observer re-reports the route beneath a closed sheet.cta_tap— the tap itself, with actaIdsuch astryorsubscribe. A tap on “Try” is not a trial, and a trial is not revenue: a verified zero-price purchase is listed as verified and not counted.checkout_started— when the app opens RevenueCat's purchase (the store sheet).payment_startedis the payment step of a checkout of your own, not the store sheet; neither is a purchase.signup,login— only if the app has accounts. There is no purchase event to send: a purchase exists on the dashboard only as a transaction the server verified.
Consent stays the person's: pass the stored decision to initialize(consent:) and call setConsent when they decide; do not force analyticsAllowed. Under restricted a purchase is still verified but carries no identity claim; under disabled or no decision the hand-over answers refusedByConsent and nothing is written.
Keep the existing RevenueCat App User ID and login, logout, restore and entitlement behavior unchanged. Do not change purchase identity to connect analytics: that needs a separately approved identity migration. Before passing appAccountToken to WebmasterID, verify the existing account-to-token mapping against the store-signed transaction; do not invent or rotate a token, assume the RevenueCat ID is that token, or overwrite a conflicting binding. A purchase may be verified without a user link; do not claim user-level revenue or LTV until the binding is proven. See RevenueCat's customer identity guidance.
The tester, on a device — the acceptance test
The first test is a real Apple sandbox purchase on a device, not a local StoreKit configuration file: Xcode's signatures are not Apple's and WebmasterID refuses them. Sign a device into a Sandbox Apple Account (App Store Connect → Users and Access → Sandbox; follow Apple's current device setup instructions for the installed iOS version), install a TestFlight or development build with the right property id, consent to analytics in the app, and buy on RevenueCat's paywall. The test passes only when all of this holds:
- RevenueCat grants access exactly as before, and the app shows nothing new to the person.
- WebmasterID verified Apple's transaction: within a few minutes the app's page shows step 6, Purchase verification, with the sandbox line “Sandbox: 1 verified; last <time>. Sandbox purchases never count.” and, under Connection status → Purchase proofs — App Store, Sandbox: Received recent, Verified by the store 1, Counted as revenue “not applicable”.
- The log shows Sandbox: the app's transaction log lists the purchase as Sandbox · never counted, Apps → Conversions says “only sandbox purchases were verified so far; nothing counts in production”, and verified revenue is unchanged.
- A resubmission adds no purchase: hand the same id over again —
alreadyQueuedon the device orduplicatefrom the server — and the verified count stays 1. - A WebmasterID failure does not touch the purchase: repeat with the sandbox connection turned off, or with the device offline during the hand-over. RevenueCat still grants access; the dashboard shows a refused proof with its reason, or nothing until the device is back online.
What this test does not prove, and nothing on the dashboard claims after it: renewals, refunds, restores and production purchases — each needs its own run, and a production purchase also needs the enabled production connection. A refusal “no App Store connection was enabled for the environment it named (Sandbox)” means the owner's step 3 was skipped, or the build reports to a property that has no sandbox connection.
Test purchases, and checking the whole chain
Sandbox and TestFlight purchases are verified like real ones and never counted as revenue — the same checks as above, for an app that sells through StoreKit 2 or in_app_purchase directly:
- Create and turn on the app's Sandbox App Store connection (Create URL, then Turn on; no Apple App ID).
- In a development or TestFlight build, buy with a Sandbox Apple Account (App Store Connect → Users and Access → Sandbox). Never use a real card to test.
- On the device,
submitorattachanswerstored(oralreadyQueued); after delivery,storeKit.diagnostics()showslastPaymentOutcomeaccepted, orduplicatefor a purchase already received;rejectedmeans the signature, the bundle id or the environment did not match an enabled connection. - The app's transaction log on the dashboard (the app's page → Open the transaction log) lists the purchase as Sandbox · never counted.
- Apps → Conversions keeps it out of the production totals, which stay as they were.
A purchase made in Xcode with a local StoreKit configuration file is signed by Xcode, not by Apple, and WebmasterID refuses it.
7. Codemagic
A minimal codemagic.yaml for the example app: analyze, test, an Android release APK with R8, and an iOS Simulator build. It signs nothing, uploads nothing and holds no secret. Three different accesses are involved, and only the first is Codemagic's business:
- Your app's repository: Codemagic needs read access to it, as for any app.
- Release signing and store upload: your certificates, profiles and keystores, in your own release workflow — not in this one.
- Downloading the SDK: anonymous. No WebmasterID GitHub token, deploy key or repository access exists for customers, and none must be added to Codemagic.
# WebmasterID consumer app — a Codemagic build with no secret of any kind.
#
# What Codemagic needs: read access to THIS repository. Nothing else — no
# WebmasterID GitHub token, no deploy key, no access to any WebmasterID
# repository: the SDK installs anonymously from pub.dev (the Flutter package),
# from the public Swift package (iOS) and from https://webmasterid.com/sdk/maven
# (Android). Release signing and store upload are a separate workflow of your
# own; this one signs nothing and uploads nothing.
#
# MANUAL ONLY: no `triggering` section, so no push, tag or pull request starts
# it. Start it from the Codemagic UI.
workflows:
webmasterid-consumer:
name: WebmasterID consumer — analyze, test, Android release APK (R8), iOS Simulator
instance_type: mac_mini_m2
max_build_duration: 60
environment:
flutter: 3.47.6
xcode: "26.6"
java: 17
vars:
# REQUIRED: your property's PUBLIC id, from the app's card in the
# dashboard (ap_ + 16 lowercase letters or digits). It is not a secret;
# it ships in the app. Left empty, the build stops at the next step.
# Define it in ONE place: here, or in a Codemagic variable group listed
# under `groups:` — then delete this line, so no empty value competes.
WMID_APP_PROPERTY_ID: ""
# Empty = production. Only an acceptance run sets a test endpoint here.
WMID_ENDPOINT: ""
scripts:
- name: The property id is set, and it is not a placeholder
script: |
set -euo pipefail
case "${WMID_APP_PROPERTY_ID:-}" in
"") echo "WMID_APP_PROPERTY_ID is empty: set your Public property ID from the dashboard."; exit 1 ;;
ap_xxxxxxxxxxxxxxxx) echo "WMID_APP_PROPERTY_ID is still the guide's placeholder."; exit 1 ;;
esac
[[ "$WMID_APP_PROPERTY_ID" =~ ^ap_[0-9a-z]{16}$ ]] || { echo "WMID_APP_PROPERTY_ID is not a public property id (ap_ + 16 lowercase letters or digits)."; exit 1; }
# Public, so printed: compare it with the Public property ID on the app's card.
echo "this build sends to property $WMID_APP_PROPERTY_ID"
- name: No WebmasterID credential on this machine (names only, never values)
script: |
set -euo pipefail
found="$(env | sed -nE 's/^([A-Z0-9_]*(SSH_KEY|GITHUB_TOKEN|GH_TOKEN|_PAT|PRIVATE_KEY)[A-Z0-9_]*)=.*/\1/p')"
[ -z "$found" ] || { echo "credential-like variables present: $found"; exit 1; }
keys="$(git config --global --name-only --get-regexp 'credential|insteadof' 2>/dev/null || true)"
[ -z "$keys" ] || { echo "git credential or URL rewrite configured: $keys"; exit 1; }
for f in "$HOME/.netrc" "$HOME/.git-credentials" "$HOME/.m2/settings.xml"; do
[ ! -e "$f" ] || { echo "credential file present: $f"; exit 1; }
done
echo "no WebmasterID credential: the SDK must install anonymously"
- name: Install — the pubspec's dependencies, from pub.dev
script: |
set -euo pipefail
flutter --version
flutter pub get
# The lock entry pub wrote: hosted on https://pub.dev, and its version.
grep -A7 '^ webmasterid_flutter:' pubspec.lock
- name: Analyze and test
script: |
set -euo pipefail
flutter analyze
if [ -d test ]; then flutter test; else echo "no test/ directory: nothing to run"; fi
- name: Android — release APK with R8
script: |
set -euo pipefail
flutter build apk --release \
--dart-define=WMID_APP_PROPERTY_ID="$WMID_APP_PROPERTY_ID" \
--dart-define=WMID_ENDPOINT="$WMID_ENDPOINT"
- name: iOS — Simulator build (no signing)
script: |
set -euo pipefail
xcodebuild -version
flutter build ios --simulator --no-codesign \
--dart-define=WMID_APP_PROPERTY_ID="$WMID_APP_PROPERTY_ID" \
--dart-define=WMID_ENDPOINT="$WMID_ENDPOINT"
- name: What was resolved (the proof that no private source was used)
script: |
set -euo pipefail
echo "--- webmasterid_flutter from pub.dev:"; grep -B1 -A4 '^ webmasterid_flutter:' pubspec.lock
echo "--- iOS SDK (public Swift package, pinned by the plugin):"
find ios -name Package.resolved -exec cat {} \; | grep -A4 webmasterid-mobile-sdk || true
echo "--- Android SDK (public Maven):"
find "$HOME/.gradle/caches" -path '*com.webmasterid*' -name '*.pom' 2>/dev/null | head -5 || true
artifacts:
- build/app/outputs/flutter-apk/app-release.apk
- build/app/outputs/mapping/release/mapping.txt
- build/ios/iphonesimulator/Runner.app
- pubspec.lock
Start it from the Codemagic UI (there is no trigger on purpose). Its first step stops the build when the id is missing, still a placeholder or not a Public property ID, and otherwise prints this build sends to property ap_… — compare that line with the card. The last step prints what was resolved: webmasterid_flutter from pub.dev, the iOS package pinned by the plugin, the Android libraries from the public Maven repository.
Your release workflow
The build that ships needs the same id, the same way: a --dart-define on flutter build ipa and flutter build appbundle. Without it the app ships without an id; the example app then stops at start and sends nothing. Define WMID_APP_PROPERTY_ID in one place — in the workflow's vars, or in a Codemagic variable group listed under groups, not both. Codemagic's documentation does not say which wins when both define it, so an empty value in one can hide the real one in the other:
# YOUR release workflow — signing and store upload stay yours. The property id
# reaches the app the same way: as a --dart-define on the build that ships.
# Without it the app has no id (the guide's example stops at start with
# "WMID_APP_PROPERTY_ID is not set"); a build that never runs the guard above
# would ship that.
workflows:
release:
environment:
vars:
# One place only: here, or a variable group under `groups:` — not both.
WMID_APP_PROPERTY_ID: ap_YOUR_PROPERTY_ID
scripts:
- name: The property id is a public property id
script: |
[[ "${WMID_APP_PROPERTY_ID:-}" =~ ^ap_[0-9a-z]{16}$ ]] || { echo "set WMID_APP_PROPERTY_ID to the Public property ID from the app's card"; exit 1; }
echo "this build sends to property $WMID_APP_PROPERTY_ID"
- name: iOS — the App Store build
script: |
flutter build ipa --release \
--dart-define=WMID_APP_PROPERTY_ID="$WMID_APP_PROPERTY_ID"
- name: Android — the Play build
script: |
flutter build appbundle --release \
--dart-define=WMID_APP_PROPERTY_ID="$WMID_APP_PROPERTY_ID"
These scripts are executed step by step in our own tests, with a stand-in for the flutter command that records what it was given; they have not been run on Codemagic's machines. A build made in Codemagic's Workflow Editor instead of YAML puts the same --dart-define=WMID_APP_PROPERTY_ID=ap_… in the build arguments of each platform.
8. Troubleshooting and updates
Start from what you can see — a build error, a field of diagnostics(), the dashboard — and read every cause listed for it: several produce the same observation. Neither the diagnostics nor the build log contains the account key, a purchase token or any secret, so both can be shared with support as they are.
The build
- flutter pub get: version solving failed, or "requires SDK version" — webmasterid_flutter needs Flutter 3.47.0 or newer (Dart 3.13). Check: Upgrade Flutter (flutter upgrade) and run flutter pub get again.
- flutter analyze after copying the example: Target of URI doesn't exist: 'package:shared_preferences/…', or The name 'MyApp' isn't a class — The example app stores the consent decision with shared_preferences, and the template's test/widget_test.dart tests the template's MyApp, which the example replaces. Check: flutter pub add shared_preferences; delete test/widget_test.dart or write a test for your own app.
- iOS build: no such module 'WebmasterID', or the plugin's package is not resolved — Swift Package Manager is turned off in this Flutter project. The plugin has no CocoaPods podspec. Check: flutter config --enable-swift-package-manager (or remove enable-swift-package-manager: false from pubspec.yaml), then flutter clean and build again. Xcode downloads the two frameworks and checks their SHA-256.
- flutter build ios prints "Updating minimum iOS deployment target to 15.0." and ios/Runner.xcodeproj changed — The project's deployment target was below iOS 15.0; Flutter raised it. That is not an error — the app now requires iOS 15.0. Check: Commit the rewritten project files. In a native Xcode project the same minimum applies: set Minimum Deployments to 15.0.
- Android build: Could not find com.webmasterid:webmasterid-android:0.3.0 — Your settings.gradle(.kts) sets RepositoriesMode.FAIL_ON_PROJECT_REPOS, so the repository the plugin adds is ignored. Check: Add maven { url = uri("https://webmasterid.com/sdk/maven") } to dependencyResolutionManagement.repositories in settings.gradle(.kts).
- Android build: uses-sdk:minSdkVersion 21 cannot be smaller than version 24 — The SDK supports Android API 24 (Android 7.0) and newer. Check: Set minSdk = 24 in android/app/build.gradle(.kts).
The app starts
- The example app stops at start: StateError WMID_APP_PROPERTY_ID … — The build has no property id, still carries a placeholder, or the value is not a Public property ID. The app refuses before the SDK starts: nothing was sent. Check: Build with --dart-define=WMID_APP_PROPERTY_ID=<the Public property ID from the app's card>; in Codemagic, see section 7 — the build log line "this build sends to property …" shows what the build received.
- initialize throws different_endpoint or consent_conflict — A second initialize in the same process named a different endpoint, or a different stored decision than the one already in force. Check: Initialize once per process with one endpoint; change consent with setConsent, not by re-initializing.
- identify throws ArgumentError, or PlatformException keychain_unavailable (iOS) — ArgumentError: the account key contained '@' or whitespace, was empty, or was longer than 128 characters — an e-mail address is refused, never hashed. keychain_unavailable: the Keychain is not reachable yet (before the device's first unlock after a restart); nothing was registered. Check: Pass your own opaque account id. After keychain_unavailable, call identify again later (next launch or foreground), or pass your own account-service appAccountToken.
Diagnostics on the device
- track returns false; queued and queuedEvents stay 0 — No consent decision is in force (deliveryHold: consentNotDecided), or the person chose disabled. That is the SDK working: nothing is collected without a decision that allows it. Check: Call setConsent when the person decides, store the decision, and pass it to initialize(consent:) at every launch. Never infer it from App Tracking Transparency.
- queuedEvents stays above 0 and attempted stays 0 — Delivery is held: deliveryHold shows consentNotDecided (no decision in force) or identityNotRestored (an earlier launch stored an account key; at most 30 seconds). Or the app runs an SDK older than iOS 1.3.0 or webmasterid_flutter 0.4.0, which on iOS sent only on flush() or a background transition. Check: Read deliveryHold. Check the version your build resolved (pubspec.lock, Package.resolved) and update it.
- lastStatusCategory: refused (HTTP 403); then queuedEvents grows and attempted stops — The server does not accept events for this id: an id it does not know (a typo, a placeholder, a deleted property), an archived property, or a workspace without service access. The answer is the same for all three, on purpose. Delivery stops for the rest of this process; queued events stay on the device. Check: Compare the id the app prints (the example shows it as Property:) with the Public property ID on the card; restore an archived app; check /settings/billing. The next app process tries again.
- lastStatusCategory: clientError (HTTP 400) and permanentlyRejected rises — The batch was refused for its content and dropped — most often a device clock more than 7 days behind or 10 minutes ahead. (A property id that is not an id, such as the placeholder ap_YOUR_PROPERTY_ID, is refused at initialize on both platforms and never sent.) A 400 is never retried. Check: Fix the device clock — the SDK sends occurred_at as the device saw it — and copy the Public property ID from the app's card.
- lastStatusCategory: serverError, transportError or rateLimited, retryState: scheduled — The attempt failed and the events are still on the device. While the app is running, the SDK retries by itself when the wait in retryInSeconds is over: a 429's Retry-After in full, otherwise at most 5 minutes. A suspended app retries when it runs again. Check: Nothing to change if it clears. A flush() sends at once if you must not wait; inside a 429's window the server may refuse it again.
The dashboard
- acknowledged > 0, but the dashboard shows nothing — The server stored the events for the property the app named. You may be looking at another property, another workspace, another environment, or another date range: the Apps page shows Production by default; a Development or TestFlight property's events appear only under that environment. Check: Compare the app's id with the card's Public property ID; check the workspace; on the Apps page pick the app in the App filter (its environment follows) or choose its environment; use a range that includes today; reload.
- The card still says "SDK not installed" — The server has received no event for THAT property — ever. Either nothing was delivered (see Diagnostics above) or the app sends with another property's id. Check: Run the first-event check in a build of the app and read acknowledged and lastStatusCategory.
- Installations on the dashboard do not match App Store or Google Play downloads — First observed installations count installation ids whose first event reached the server in the period. An installation id exists only under analyticsAllowed, after the app integrated the SDK and sent an event; a reinstall or resetIdentity creates a new one. Downloads are a store's number and are not counted here. Check: Compare like with like: events and active installations since the integrated version shipped.
- Basic events arrive, but revenue or attribution is empty — A separate question from basic events: purchases need the purchase integration and a store connection (section 6); attribution needs the data its page describes. Basic events arriving proves the SDK, the property and the ingest work. Check: Read the Conversions and Attribution pages' own requirements; nothing in the basic setup above changes them.
- Events stopped after the subscription lapsed — Service access is checked at ingest: a workspace without an active plan or legacy access gets 403. Check: Open /settings/billing. Events the apps queued meanwhile stay on the devices (up to 7 days) and are delivered by a later app process once the property accepts again.
Updating and going back
- Flutter:
flutter pub upgrade webmasterid_flutter. The plugin pins the native SDK versions it was built with; do not override them. To hold a version, pin it exactly:webmasterid_flutter: 0.4.1. - Native iOS: change the version rule in Xcode or in
Package.swift(exact:holds a version). Native Android: change the version in the dependency line. - Published versions never change: a release, its assets and their checksums are immutable, and a fix is a new version. Every published version stays installable, so going back is pinning the previous one. The first published version of the Flutter package was 0.3.0; 0.4.1 pins iOS 1.3.1 and Android 0.3.0. Going back below iOS 1.3.0 or
webmasterid_flutter0.4.0 brings back the earlier delivery: on iOS, only onflush()or a background transition.
The package reference for every call is the README of webmasterid_flutter on pub.dev and the README of the public Swift package. For the tracker on websites, see Install the tracker.