FAQ

Common questions about integrating and using the Adtrace Android SDK, from dependencies and testing to events, deep links, uninstall tracking, and WebBridge.

Integration and dependencies

I keep seeing "package not resolved"

Check	Action
Artifact coordinates	Search Maven Central for `io.adtrace` and confirm group ID, artifact ID, and version.
Gradle sync	After changing dependencies, sync the project and rebuild.
Network / VPN	In some regions a VPN is required to reach Maven Central.

See Get the Adtrace SDK.

Which version of the SDK should I use?

Use the latest stable release when possible. Older versions may still work, but support and fixes focus on current releases. Check the Android SDK releases page for version notes.

What if I use a deprecated version?

A deprecated SDK may work for the features you use today, but Adtrace does not fully support outdated versions. Plan an upgrade before your next release. If you need guidance, contact Adtrace support.

I do not want to use Maven Central

You can integrate the SDK from the aar or jar files published with each release. Behavior is the same as the Maven dependency. Download builds from the releases page.

What if I do not add Google Play Services?

The SDK runs without throwing an exception, but advertising ID and related features will not work. Add Google Play Services for full functionality. See Add Google Play Services.

What if I do not add Install Referrer?

The SDK runs without throwing an exception, but store campaign attribution from the install referrer will be limited. Add the Install Referrer library for full attribution. See Add Install Referrer.

Can I remove `AdTraceReceiver` from `AndroidManifest.xml`?

Google deprecated the install broadcast as the long-term referrer delivery method (March 2020), but you still need a receiver if you rely on the INSTALL_REFERRER broadcast.

Your setup	What to do
No custom `INSTALL_REFERRER` receiver	Keep `AdTraceReceiver` inside the `<application>` tag.
You already have your own receiver	Follow Multiple broadcast receivers so Adtrace still receives the referrer.

Google Play rejected my update because of the `AD_ID` permission

Google Play applies Families policies based on your target audience.

Audience	Action
Apps solely for children (API 33+)	Do not request `AD_ID`. Remove the permission and enable the Google Play Kids option.
Apps not solely for children	Keep the permission and declare that you are not targeting children only. Disable the Kids option in the SDK if needed.

Can I see data in the panel while using `Environment.SANDBOX`?

Yes. The SDK sends data in both production and sandbox. Sandbox lets you separate test traffic from real users in the panel. Always switch to AdTraceConfig.ENVIRONMENT_PRODUCTION before release.

I already have a class that extends `Application`. Do I need another one?

No. Add Adtrace initialization to your existing Application subclass. The SDK must hook into app start and background transitions via AdTrace.onCreate, AdTrace.onResume, and AdTrace.onPause. See Initialize the Adtrace SDK.

What is the minimum requirement for Adtrace to work?

With required dependencies in place, you must:

Build an AdTraceConfig with context, appToken, and environment.
Call AdTrace.onCreate(config).
Call AdTrace.onResume() and AdTrace.onPause() in the correct lifecycle callbacks.

After that, the SDK sends Install and Session automatically when session tracking is configured. See Configure session tracking.

Is calling `AdTrace.onCreate` enough to send Install?

No. onCreate applies configuration only. Call AdTrace.onResume() to start the SDK and trigger install and session logic.

Testing

How do I configure Adtrace for testing?

Set AdTraceConfig.ENVIRONMENT_SANDBOX (switch to production before release).
Set log level to verbose. See Log level.
Install on a fresh device with the device connected to Logcat.

Follow Test the integration for Testing Console steps.

What is a "fresh device"?

After the first open, the SDK stores state on the device. To verify a new Install, use a device that has never run your app with Adtrace, or forget the device and clear app data.

After forgetting a device, uninstall the app (or clear storage), reinstall, and open again.

How do I forget a device?

When you test install attribution, Adtrace assigns a persistent device ID. Reinstalling without a reset may not count as a new install.

Open the Adtrace panel.
Go to Settings → Testing Console.
Enter your device ID.
Click Forget Device.

How do I get my device ID?

Adtrace uses several identifiers. The two most useful for testing:

ID	Description	How to get it
Google Advertising ID	UUID from Google Play services (`gps_adid`)	Logcat after verbose logging, or Device IDs APIs
Adtrace device ID (`adid`)	ID assigned by Adtrace for your app on the device	Logcat or Device IDs documentation

With sandbox and verbose logs enabled, search Logcat for gps_adid and adid:

gps_adid:   7c67ef26-830e-49b7-8948-b868b19bf4b3
"adid"  :   "mhxd6or7d3u57fnbdy2r4urdrdxr7tlr"

Events and revenue

What is `eventToken`?

An eventToken is the string identifier for an event you create in the Adtrace panel. It has no meaning outside your project; use it when building AdTraceEvent in code. See Event tracking.

What is a unique event?

A unique event is recorded once per app lifetime (for example account registration). Enable it in the panel when creating the event. No extra SDK code is required.

How many events can I send per user or time period?

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

How many different events can I define?

There is no hard limit in the panel, but too many distinct event names makes analysis harder. Prefer a small set of reusable events with value parameters:

Avoid	Prefer
`purchase_cloth`, `purchase_hat`, `purchase_watch`, …	One `purchase` event with parameters for item type
One event name per screen or button	`open_page`, `add_to_cart`, `share`, `purchase`

See Track events.

How do I know an event was sent successfully?

Register an event success/failure callback. See Send callback information. During testing, also watch Logcat with verbose logging.

Does Adtrace convert revenue by currency?

No. The currency code labels revenue so values are not mixed in reports. For consistent analytics, send revenue in one currency (for example USD, IRR, or your local unit).

Do not send revenue through event value parameters. Use the dedicated revenue API on the event object.

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

Double taps or slow networks can fire the same purchase event multiple times. Each duplicate adds revenue to your totals.

Pass a unique order ID when tracking revenue. If the same order ID is sent again, Adtrace deduplicates it. See Revenue deduplication.

How can I add custom data to an event?

Use callback parameters (key/value strings) on the event. See Event value parameters.

How many parameters can I add to an event?

There is no fixed limit. Use a consistent key schema across events so data stays clean:

Avoid	Prefer
Different keys per event (`first_name`, `name`, `cost`)	Shared keys: `name`, `item_type`, `item_name`, `user_id`
Revenue or timestamps in parameters	Use revenue API and built-in event timestamps

Sessions

How should I send a session?

After session tracking is wired to your activity lifecycle, the SDK sends sessions automatically. No manual session API calls are required.

How do I know a session was sent successfully?

Use session success/failure callbacks. See Send callback information. During testing, confirm in Logcat with verbose logging.

Deep linking

How do I define a deeplink for Adtrace?

Deeplinks are Android app links or intent filters you define. Adtrace passes deeplink parameters through tracker URLs without modifying them. Configure your app intent filters and tracker settings in the panel. See Deep linking.

What is deferred deeplink?

A deferred deeplink applies when the user clicks a link before the app is installed. After install and first open, the SDK delivers the deferred URL to your app. See Deferred deeplink.

Do I need a different deeplink type for deferred deeplinking?

No. Use the same deeplink format. Configure the tracker correctly in the panel. See Deferred deeplink.

Is SDK configuration required for deeplinking?

Scenario	Panel + app deeplink support	SDK deeplink APIs
Standard (app already installed)	Required	Not required
Deferred (install after click)	Required	Required. See Deferred deeplink

Uninstall and reinstall

What is required to track uninstall?

Implement Firebase Cloud Messaging and send the FCM token with AdTrace.setPushToken. Adtrace uses silent push to detect uninstalls. See Uninstall and reinstall tracking and Set up uninstall tracking.

What is silent push?

Silent push is a data-only FCM message with no visible title or body. Adtrace sends about one per day to check whether your app is still installed. Your FirebaseMessagingService must detect empty title/body and avoid showing a notification. See Implementation examples.

Why does my app show blank notifications?

You are not filtering silent push messages. Handle messages with empty title and body without displaying a notification. See Uninstall implementation examples.

Is uninstall an event? Does it appear instantly in the panel?

No. Uninstall is not an SDK event like purchase or login. It is detected through silent push and FCM token validation.

Panel data is not real-time. Updates often take up to 24 hours or longer, depending on when the silent push runs and FCM responds.

When does a reinstall appear in the panel?

A reinstall is recorded when a user who previously had your app installs and opens it again after uninstall (or after the prior install is no longer active), and Adtrace matches them as a known device.

Reinstall is not a new first-time install.
Enable uninstall tracking (FCM key in panel + setPushToken in the app) for reliable reinstall detection.
Reinstall status appears after processing, with similar delay as uninstall checks.

Where do I get the Firebase JSON file for the panel?

The file is not a Firebase console download. It is a Google Cloud service-account private key (JSON) for FCM HTTP v1:

Open the Google Cloud project linked to your Firebase app.
Create a custom IAM role, service account, and JSON key. Step-by-step: Set up uninstall tracking.
Upload the JSON in the Adtrace panel for your app's FCM connection.

SDK signature

Does the panel "App Version" field have to match my app version?

No. App Version on an SDK Signature is the signature version, not your Android versionName or versionCode. One signature version can cover multiple app releases. Use it to distinguish signature definitions.

What is Secret ID (Security ID)?

Secret ID is the identifier Adtrace assigns when you create a signature in the panel. Pass it as the first argument to setAppSecret(secretId, info1, info2, info3, info4). It ties SDK traffic to that signature for reporting and fraud checks. See SDK signature.

Can I test signatures before release?

Yes.

Create test (or production) signatures in the panel.
Build one installable APK/AAB per signature with matching setAppSecret values.
Fresh install each build on a test device.
Send test events and enable Show by SDK Signature in Statistics.

When reusing the same device for another signature: uninstall, forget the device in the Testing Console, then install the next build.

What happens if Fraud Detection is on but an APK has no signature?

Installs from APKs without the expected signature can be marked as fraud. Enable Fraud Detection only when every shipped APK for that channel includes the correct setAppSecret values.

WebBridge

My app is one activity with a WebView. How does Adtrace work?

Adtrace WebBridge connects the native Android SDK to JavaScript in your WebView. The native SDK handles network and data; WebBridge exposes the same APIs to the web layer.

App entry point	Initialize from
User lands on web content first	Web side. See WebBridge (WebView).
User starts in native UI, then opens WebView	Native side first (Case B), then bridge to web. See WebBridge (WebView).

Implement features (events, push token, and so on) on whichever side the user interacts with.

Can I call `AdTrace.onCreate` from both native and JavaScript?

No. There is only one SDK instance per process. Initialize once:

Case A (WebBridge-only): call AdTrace.onCreate from JavaScript only
Case B (hybrid): call AdTrace.onCreate from native only; JS uses trackEvent without onCreate

Calling both logs AdTrace already initialized. See WebBridge (WebView).

Can WebBridge match native SDK functionality?

Yes. Every native API documented for Android has a WebBridge equivalent. See the Android SDK README for paired native and WebView samples.

Can I use Adtrace for a PWA?

For a standalone Progressive Web App in the browser, use the Adtrace Web SDK. If the PWA runs inside an Android WebView, use the Android SDK plus WebBridge.

Can I use Adtrace for TWA?

Yes. Trusted Web Activity is supported. See the TWA documentation.

Do I need to add SDK scripts on the web side?

Yes. Import the WebBridge asset files so web and native share the same data structure. See WebBridge JS files.

Can I use WebBridge and Web SDK in the same project?

Yes, with separation:

Context	SDK
Page loaded inside the app WebView	WebBridge assets
Page loaded in a mobile browser	Web SDK

Which files do I import on the web side?

Add the JavaScript assets from the WebBridge assets folder to your web project. Follow WebBridge (WebView).

Where are sample WebBridge projects?

Project	Link
Android WebBridge example	example-app-webbridge
Web side (Next.js)	nextjs-webview
Web side (Next.js 2)	nextjs-example

Which platforms support WebBridge?

All popular web frameworks that can load the bridge assets (React, Vue, Angular, plain HTML, and others).

How many events can WebBridge send per day? How many parameters per event?

Same limits as the native SDK:

How many events per user or time period?
How many different events can I define?
How many parameters can I add to an event?

How do I verify WebBridge is tracking all events?

Use event callbacks and verbose Logcat. See How do I know an event was sent successfully? and Test the integration.

Device IDs and attribution

How do I receive attribution data?

Set an attribution listener. The SDK calls it when attribution is received or updated. See User attribution.

How long does attribution take?

There is no fixed time. It depends on network speed and server load, but it is usually within a few seconds. Implement your logic in the attribution callback rather than polling.

What is GPS AdId / Google Advertising ID / Google Play Services Ad ID?

The advertising ID is a unique, user-resettable ID for advertising from Google Play services. See Google's documentation.

How do I get the Google Advertising ID?

The Adtrace SDK reads it asynchronously. Do not block app logic waiting for the callback. See Device IDs.

I keep getting `00000000-0000-0000-0000-000000000000` or `null` for the advertising ID

Cause	Notes
User reset or opted out	The user may have deleted or limited ad ID access.
Missing `AD_ID` permission (Android 13+)	Declare `<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>` in the manifest. See Add permissions.
Emulator without Google Play	Use a physical device or an emulator image with Google Play.

Is there a runtime permission for AD_ID?

No. Declare the permission in the manifest only.

What if I do not add the AD_ID permission?

On older Android versions, behavior may be unchanged. On Android 13 and later, features that require the advertising ID (for example reinstall tracking and S2S events) will not work without the permission. The rest of the SDK continues to function.

Where can I view or reset my advertising ID?

On the device: Settings → Google → Ads.

Some devices do not support Google Ad ID (for example Huawei)

Adtrace supports devices that use OAID instead of Google Ad ID. Add the OAID plugin to your project. See Huawei and OAID.

Troubleshooting

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

This typically happens during install testing. Uninstalling and reinstalling is not enough to trigger a new install — the Adtrace servers still hold the previous session state for that device.

Find the app_token and gps_adid values in the error log.
Open the Testing Console in the Adtrace panel and use Forget Device.
Uninstall the app, clear app data, then reinstall and reopen.

After the device is forgotten, the console returns Forgot device. If it says Advertising ID not found, the values were incorrect.

I'm not seeing "Install tracked" in logs

Simply re-running the app from Android Studio does not wipe the SDK's local state files. The SDK sees those files on relaunch and treats it as a session, not a new install.

To simulate a fresh install:

Uninstall the app from the device completely.
Forget the device in the Testing Console.
Reinstall from Android Studio. You should then see Install tracked in Logcat.

Is my broadcast receiver capturing the install referrer?

Test the broadcast receiver manually with adb:

adb shell am broadcast \
  -a com.android.vending.INSTALL_REFERRER \
  -n com.your.appname/io.adtrace.sdk.AdTraceReferrerReceiver \
  --es "referrer" "adtrace_reftag%3Dadt1ex4%26utm_source%3Dnetwork"

Replace com.your.appname with your app's package ID. With verbose logging enabled you should see a log like:

V/AdTrace: Referrer to parse (adtrace_reftag=adt1ex...) from reftag

Important

Do not use & unencoded in adb commands — adb will cut the referrer at the first &. URL-encode the entire referrer value.

If you use a custom broadcast receiver, replace io.adtrace.sdk.AdTraceReferrerReceiver with your receiver class name.

Can I trigger an event at application launch?

Tracking events inside your Application.onCreate produces inaccurate install and session counts. Application.onCreate is called by both the OS and system events, not only by user-triggered app launches. The Adtrace SDK is initialized at that point but not yet started.

Goal	Recommended approach
Track something after install	Use the attribution callback
Track something when the user opens the app	Put the call in `Activity.onCreate` for the relevant activity

SDK is initialized but events are dropped

Calling SDK methods before AdTrace.onCreate is complete causes actions to be silently ignored or dropped:

Action called before init	Result
`trackEvent`	Event is dropped permanently
`setEnabled(false)`	Toggle is ignored
`setOfflineMode(true)`	Has no effect at startup

Initialize the SDK as early as possible in Application.onCreate, then queue any deferred actions to run after AdTrace.onCreate returns.

Session tracking and DAU numbers look wrong

DAU counts can be off if the SDK initializes late — for example only when the user navigates to a specific screen rather than at app start.

Scenarios that cause incorrect DAU:

User opens the app and deletes it before the SDK-initialized screen is reached — install is never tracked.
User opens the app before midnight, SDK initializes after midnight — the install and first session are attributed to the wrong day.

Fix: initialize in Application.onCreate (or the earliest possible lifecycle callback), not in an activity.

Integration and dependencies​

I keep seeing "package not resolved"​

Which version of the SDK should I use?​

What if I use a deprecated version?​

I do not want to use Maven Central​

What if I do not add Google Play Services?​

What if I do not add Install Referrer?​

Can I remove AdTraceReceiver from AndroidManifest.xml?​

Google Play rejected my update because of the AD_ID permission​

Can I see data in the panel while using Environment.SANDBOX?​

I already have a class that extends Application. Do I need another one?​

What is the minimum requirement for Adtrace to work?​

Is calling AdTrace.onCreate enough to send Install?​

Testing​

How do I configure Adtrace for testing?​

What is a "fresh device"?​

How do I forget a device?​

How do I get my device ID?​

Events and revenue​

What is eventToken?​

What is a unique event?​

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

How many different events can I define?​

How do I know an event was sent successfully?​

Does Adtrace convert revenue by currency?​

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

How can I add custom data to an event?​

How many parameters can I add to an event?​

Sessions​

How should I send a session?​

How do I know a session was sent successfully?​

Deep linking​

How do I define a deeplink for Adtrace?​

What is deferred deeplink?​

Do I need a different deeplink type for deferred deeplinking?​

Is SDK configuration required for deeplinking?​

Uninstall and reinstall​

What is required to track uninstall?​

What is silent push?​

Why does my app show blank notifications?​

Is uninstall an event? Does it appear instantly in the panel?​

When does a reinstall appear in the panel?​

Where do I get the Firebase JSON file for the panel?​

SDK signature​

Does the panel "App Version" field have to match my app version?​

What is Secret ID (Security ID)?​

Can I test signatures before release?​

What happens if Fraud Detection is on but an APK has no signature?​

WebBridge​

My app is one activity with a WebView. How does Adtrace work?​

Can I call AdTrace.onCreate from both native and JavaScript?​

Can WebBridge match native SDK functionality?​

Can I use Adtrace for a PWA?​

Can I use Adtrace for TWA?​

Do I need to add SDK scripts on the web side?​

Can I use WebBridge and Web SDK in the same project?​

Which files do I import on the web side?​

Where are sample WebBridge projects?​

Which platforms support WebBridge?​

How many events can WebBridge send per day? How many parameters per event?​

How do I verify WebBridge is tracking all events?​

Device IDs and attribution​

How do I receive attribution data?​

How long does attribution take?​

What is GPS AdId / Google Advertising ID / Google Play Services Ad ID?​

How do I get the Google Advertising ID?​

I keep getting 00000000-0000-0000-0000-000000000000 or null for the advertising ID​

Is there a runtime permission for AD_ID?​

What if I do not add the AD_ID permission?​

Where can I view or reset my advertising ID?​

Some devices do not support Google Ad ID (for example Huawei)​

Troubleshooting​

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

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

Is my broadcast receiver capturing the install referrer?​

Can I trigger an event at application launch?​

SDK is initialized but events are dropped​

Session tracking and DAU numbers look wrong​

Related​