Skip to main content
Version: 3.0.0+

FAQ

Common questions about iOS SDK integration, testing, App Tracking Transparency, events, and sessions.

Integration​

Where can I see real examples of implementation?​

The Adtrace iOS GitHub repository includes example projects for different use cases:

Can I use Adtrace in Swift projects?​

Yes. The iOS SDK supports both Objective-C and Swift. See Getting started with the iOS SDK.

How do I use Swift Package Manager instead of CocoaPods?​

Add the SDK via File → Add Packages… and enter the repository URL:

https://github.com/adtrace/adtrace_sdk_iOS

See Add the Adtrace SDK for SPM, CocoaPods, and Carthage options.

Does Adtrace provide an XCFramework?​

Yes. Each release includes prebuilt frameworks on the GitHub releases page. You can also build locally using the build script in the repository.

Where can I find my app token?​

Create an app in the Adtrace panel. Adtrace generates a hash-like app token that identifies your application to the backend. Find it under Settings → App Token.

I don't see any logs from Adtrace​

Adtrace prints logs at different levels. Set log level to Verbose to see all output. See Set up logging.

Make sure you are using ADTEnvironmentSandbox during development — sandbox mode is intended for testing and log output.

I don't see any changes in Adtrace panel statistics​

When the SDK is integrated correctly, it sends data to the backend and statistics appear in the panel. If you see no changes, check:

What is the minimum requirement for the Adtrace SDK?​

Adtrace offers many features, but analytics and statistics require basic integration:

Review the example apps if you need a working reference.

Sandbox mode vs production mode​

During integration and testing, set the environment to ADTEnvironmentSandbox. This separates test traffic from production and enables useful log output. Switch to ADTEnvironmentProduction before release.

See Add the Adtrace SDK. For maximum log detail during testing, set log level to Verbose in Set up logging.

Testing​

How do I make sure everything is working?​

Before other features, Adtrace needs the app to open and an install to be recorded on the device. Then verify:

Follow Test the integration for full Testing Console steps.

How do I know install is tracked?​

Two options:

Check install via logs​

Use sandbox mode first. In verbose logs, search for response objects from the backend. If the response contains an adid field with a hash-like value, install was tracked.

Check install via Testing Console​

Open Settings → Testing Console in the Adtrace panel.

Provide a device identifier. If your app can read IDFA (with user authorization), use IDFA. Otherwise, find primary_dedupe_token in logs and use that value.

What is a "fresh device"?​

When an app is installed on a device, that device is remembered. Uninstalling and reinstalling does not count as a new install. For install testing, use a device that has never recorded an install for your app — a "fresh device."

How do I "forget" my device?​

In the Adtrace panel, go to Settings → Testing Console, enter your device ID, and clear its data from the backend.

Is the panel configured for what I want to see?​

When viewing statistics, confirm:

  • Locale and time zone
  • Selected date interval
  • Fraud detection settings
  • Active filters

Why is there no change in installs after reinstalling?​

Once a device has installed your app, Adtrace remembers it. Reinstalling immediately after uninstall does not create a new install. See Fresh device and Forget my device.

App Tracking Transparency​

Does Adtrace make my app ask for tracking authorization?​

No. By default, the Adtrace SDK does not request App Tracking Transparency authorization. IDFA improves matching, but Adtrace works without it using SDK-generated identifiers. You can disable ATT-related behavior if you do not want authorization prompts.

See Add iOS frameworks and App Tracking Transparency.

How do I know if the user allowed app-tracking authorization?​

Use the App Tracking Transparency wrapper or check authorization status directly. The SDK can report consent state to the backend when you use the built-in wrapper.

See App Tracking Transparency and Add iOS frameworks.

Events and revenue​

What is eventToken?​

An Adtrace event is identified by a string token — a set of characters with no inherent meaning. When you create an event in the Adtrace panel, you receive its token to use in code.

See Event tracking.

What is a unique event?​

A unique event is received only once per app lifetime — useful for one-time actions such as account creation. Configure this in the panel when creating the event; no extra SDK code is required.

How many events can I track per user or time period?​

There is no limit. You can send any number of events at any interval.

How many different events should I define?​

There is no hard technical limit, but keep your event schema manageable. Prefer a small set of reusable events with value parameters over dozens of narrowly named events.

Avoid:

event 1: purchase_cloth
event 2: purchase_hat
event 3: purchase_watch
...

Prefer:

event 1: purchase
event 2: open_page
event 3: add_to_cart
event 4: share

See Event tracking for parameters, revenue, and deduplication.

How do I confirm an event was sent?​

The SDK provides success and failure callbacks for each event. See Event and session callbacks. You can also inspect verbose logs during sandbox testing.

Does Adtrace convert revenue by currency?​

No. The currency you attach to revenue separates values in reporting; Adtrace does not perform currency conversion. Use a single currency consistently (for example Toman, Rial, or USD).

Do not send revenue data through event value parameters. Use the dedicated revenue API instead. See Record event revenue.

Why is revenue deduplication important, and how do I use it?​

Event revenue is often compared against real purchase data. Users may tap a purchase button multiple times when the app is slow to respond, sending duplicate revenue for one purchase.

Assign a unique orderId per purchase when tracking revenue. If the same event fires more than once with the same order ID, Adtrace deduplicates it.

See Revenue deduplication.

How can I add custom information to an event?​

Use value parameters — string key/value pairs attached to an event. You do not need a separate event token for every variation.

See Event value parameters.

How many parameters can I add to an event?​

There is no hard limit, but use a consistent key structure across events.

Avoid:

event 1: { "first_name": "John", "last_name": "Brown", "time": "15:49PM" }
event 2: { "name": "John Brown", "cost": "1000$", "date": "10-8-2021" }

Prefer:

event 1: { "name": "John Brown", "item_type": "mobile", "item_name": "Samsung Galaxy S23 Ultra", "user_id": "123456789" }
event 2: { "name": "Sara Wills", "item_type": "keyboard", "item_name": "Keychron Q6", "user_id": "987654321" }

Events already include timestamps; do not duplicate date/time in value parameters.

Sessions​

How should I send a session?​

After basic integration, Adtrace sends sessions automatically. No additional code is required.

See Integration.

How do I confirm a session was sent?​

Sessions expose success and failure callbacks. See Event and session callbacks.

Troubleshooting​

Issues with delayed SDK initialization​

Initialize the Adtrace SDK in didFinishLaunching or didFinishLaunchingWithOptions in your app delegate — as early as possible. Delaying initialization affects the following:

FeatureEffect of delayed init
Event trackingAny trackEvent call before init is dropped permanently
Offline modeNot persisted — always resets to false
Enable / disableToggle is ignored before init; state persists from last init
Deep link reattributionappWillOpenUrl: before init — attribution data is permanently lost
Session trackingDAU numbers can be wrong; installs may never be reported

If the SDK cannot be initialized first thing, build a custom queueing mechanism in your app to hold calls until after appDidLaunch returns.

Session tracking and DAU​

If the SDK initializes late — for example only when a specific view controller loads — these situations arise:

  • User opens and deletes the app before reaching the SDK-initialized screen → install never tracked.
  • User opens before midnight, SDK initializes after midnight → data attributed to the wrong day.

Always call Adtrace.appDidLaunch(config) in didFinishLaunching / didFinishLaunchingWithOptions.

I'm seeing "Adtrace requires ARC" build error​

Your project is not using Automatic Reference Counting. Options:

  1. Recommended: Migrate the project to use ARC.
  2. Alternative: Enable ARC only for Adtrace source files. In Xcode, open Build Phases → Compile Sources, select all Adtrace files, and set Compiler Flags to -fobjc-arc.

I'm seeing [UIDevice adtTrackingEnabled]: unrecognized selector error​

This happens when the SDK framework is added without the required linker flag.

Add -ObjC to Other Linker Flags in your Xcode target's Build Settings. The SDK includes Objective-C categories which require this flag to load correctly.

I'm seeing "Session failed (Ignoring too frequent session.)" error​

This typically happens during install testing. Reinstalling the app alone is not enough — the Adtrace server still holds the previous session state for that device.

Find the app_token and either adid or idfa values in the error message:

Session failed (Ignoring too frequent session. Last session: ..., interval: XXs, min interval: 20m)
(app_token: {yourAppToken}, adid: {adidValue})

Then open one of these URLs in a browser (fill in the values):

http://app.adtrace.com/forget_device?app_token={yourAppToken}&adid={adidValue}
http://app.adtrace.com/forget_device?app_token={yourAppToken}&idfa={idfaValue}

Forgot device means success. Device not found means the values were incorrect or the device was already forgotten.

I'm not seeing "Install tracked" in logs​

Re-running from Xcode does not wipe the SDK's local state files. The SDK sees those files and treats it as a session, not a new install.

To simulate a fresh install:

  1. Completely uninstall the app from the device.
  2. Forget the device using the Testing Console or the forget_device URL above.
  3. Run from Xcode on the test device you should then see Install tracked in the console.

I'm seeing "Unattributable SDK click ignored" message​

This is not an integration error. It is caused by Apple's iAd.framework (version 3+), which artificially generates sdk_click packages when an app opens without an actual iAd banner click. The Adtrace backend detects these and ignores them:

[Adtrace]v: Response: {"message":"Unattributable SDK click ignored."}
[Adtrace]i: Unattributable SDK click ignored.

This message means the backend correctly rejected a fabricated click that could have wrongly attributed your user. No action is required.

I'm seeing incorrect revenue data in the dashboard​

The Adtrace SDK sends exactly the number you pass to setRevenue:currency:. Neither the SDK nor the backend modifies the amount. If the dashboard shows unexpected values, the issue is in the logic that calculates the amount before passing it to setRevenue.

Checklist:

  • Verify the method that computes your revenue amount returns the correct value.
  • Call trackEvent only after the purchase completes (e.g., after SKPaymentTransactionStatePurchased).
  • Do not send revenue through event value parameters — use the dedicated setRevenue:currency: API only.

See Record event revenue.