Skip to main content

AdTrace SDK Integration & Troubleshooting Guide

Android​

  1. Add AdTrace SDK to Your Project

    • Integrate via Maven Central or download AAR/JAR from official releases.
    • If "package not resolved," check repository settings and use VPN if needed.

  2. Add Required Dependencies

    • Google Play Services: Add to project for advertising ID collection. Without it, some features are unavailable.
    • Install Referrer: Add for campaign attribution. Without it, campaign data may be missing.
    • Permissions: Add <uses-permission android:name="com.google.android.gms.permission.AD_ID"/> to AndroidManifest.xml (required for Android 13+). If targeting children, do not request AD_ID and enable Google Play Kids option.

  3. Basic SDK Setup

    • In Application class, initialize AdTrace:
      • Call AdTrace.onCreate(config) with valid AdTraceConfig (context, appToken, environment).
      • Call AdTrace.onResume() in onResume() and AdTrace.onPause() in onPause().
    • If you already have an Application class, add AdTrace initialization there.

  4. Testing the Integration

    • Set environment to AdTraceConfig.ENVIRONMENT_SANDBOX for testing.
    • Set log level to VERBOSE.
    • Use a fresh device or use "Forget Device" in AdTrace panel.
    • Install and run app, monitor logs for gps_adid and adid.
    • If issues:
      • Check dependencies/permissions.
      • Ensure correct initialization.
      • Review logs for errors/missing data.

  5. Deep Linking

    • For standard deep links, configure app and AdTrace tracker settings.
    • For deferred deep links, ensure app and tracker are set up for deferred deep linking in AdTrace panel.
    • No special SDK methods for standard deep links; deferred deep links require following SDK docs.

  6. Event Tracking

    • Define events in AdTrace panel and use tokens in app.
    • Use value parameters for event data (key-value pairs).
    • For revenue events, provide unique order ID to prevent duplicates.
    • Monitor event callbacks/logs for confirmation.

  7. Session Tracking

    • Sessions tracked automatically after setup.
    • Use session callbacks to monitor status.

  8. Uninstall Tracking

    • Implement Firebase Messaging Service.
    • Handle silent push notifications to avoid empty notifications.

  9. Attribution

    • Set up attribution callback to receive data.
    • Attribution usually received within seconds after install.

  10. Device IDs

    • AdTrace collects Google Advertising ID (gps_adid) and its own AdTrace device ID (adid).
    • If you get 00000000-0000-0000-0000-000000000000 or null, check permissions/device settings.
    • Some devices (e.g., Huawei) use OAID; add OAID plugin if needed.

Troubleshooting Checklist:

  • SDK/package not resolved? → Check repository/network.
  • Missing Google Play Services? → Add dependency.
  • Missing Install Referrer? → Add dependency.
  • Permission issues? → Update AndroidManifest.xml.
  • Not seeing data in panel? → Recheck setup, logs, device state.
  • Deep link/event/session/uninstall/attribution/device ID not working? → Review relevant section and check logs.

iOS​

  1. Add AdTrace SDK to Your Project

    • Integrate via CocoaPods, SPM, or download from official releases.
    • Supports both Objective-C and Swift projects.
    • For SPM: File > Add Packages... and use the SDK repo URL.

  2. Basic SDK Setup

    • Add SDK to project and integrate per official docs.
    • Initialize AdTrace in your app delegate with your app token and environment.
    • Set environment to ADTEnvironmentSandbox for testing, ADTEnvironmentProduction for release.
    • Set log level to Verbose for full logs.

  3. Testing the Integration

    • Use a fresh device or "Forget Device" in AdTrace panel.
    • Check logs for adid in response to confirm install is tracked.
    • Use Testing Console in AdTrace panel to verify device status.

  4. Event Tracking

    • Define events in AdTrace panel and use tokens in app.
    • Use value parameters for event data (key-value pairs).
    • For revenue events, provide unique order ID to prevent duplicates.
    • Monitor event callbacks/logs for confirmation.

  5. Session Tracking

    • Sessions are tracked automatically after setup.
    • Use session callbacks to monitor status.

  6. Attribution

    • Set up attribution callback to receive data.
    • Attribution usually received within seconds after install.

  7. Device IDs

    • AdTrace collects IDFA (if authorized) and its own AdTrace device ID.
    • If you get 00000000-0000-0000-0000-000000000000 or null, check permissions/device settings.

  8. App Tracking Transparency

    • AdTrace does not require tracking authorization, but can use IDFA if available.
    • You can disable all tracking requests if desired.

Troubleshooting Checklist:

  • SDK not integrated? → Check docs/examples.
  • Not seeing data in panel? → Recheck setup, logs, device state.
  • Event/session/attribution/device ID not working? → Review relevant section and check logs.

Flutter​

  1. Add AdTrace Flutter SDK

    • Search for adtrace on pub.dev and add the latest version to your project.
    • For specific versions, see SDK releases.

  2. Implementation

    • Follow both native and Dart code documentation.
    • Integrate per official docs.
    • Make sure to call Resume and Pause to app lifecycle according to the docs, this must be in the root widget.

  3. Testing

    • If you don't see data on the dashboard:
      • Double-check integration (both native and Dart).
      • Check dashboard settings (time, data type, fraud settings).
      • Contact support if needed.

  4. Deferred Deep Linking

    • Ensure tracker URL is correct and probabilistic matching is enabled if needed.
    • Uninstall app, "Forget Device" in backend, click tracker URL, reinstall app, and check logs for callback.

  5. Install Tracking Issues

    • If install tracking works in sandbox but not production, check for obfuscation (ProGuard, R8, etc.) and follow proguard docs.

  6. Build Issues

    • If you see Could not build module 'adtrace_sdk', set Allow Non-modular Includes in Framework Modules to YES in Build Settings.
    • If app crashes after adding SDK, ensure you use the latest version.

  7. Event Tracking

React Native​

  1. Add AdTrace React Native SDK

    • (Refer to official docs)
    • Use yarn may works better in some cases.

  2. Implementation

    • Integrate SDK according to documentation.
    • Use event and value parameter APIs as needed.
    • Make sure to reference Adtrace to one signle call (always refer to same instance for calls on Adtrace lib)
    • Make sure that Adtrace instance is called in the root of the components (whenever app opens, it will be called)

  3. Testing & Troubleshooting

    • If you don't see data, double-check integration and dashboard settings.
    • For event tracking, use the event API and monitor logs.
    • Clean andriod build folder and ios Pods related caches and re-download packages again.

Unity​

  1. Add AdTrace Unity SDK

    • (Refer to official docs)

  2. Implementation

    • Use Event objects to trigger events anywhere in your app.
    • To add custom parameters, use eventValueParams for unlimited key-value pairs.

  3. Testing & Troubleshooting

    • If you don't see data, double-check integration and dashboard settings.
    • For event tracking, use the event API and monitor logs.

Web​

  1. Add AdTrace Web SDK

    • (Refer to official docs and FAQ for details.)

  2. General Info

    • First session = install. Additional actions = events.
    • Attribution uses AdTrace-generated click ID (reftag).
    • No customizable attribution window for clicks; attribution is immediate.
    • Inactivity window for reattribution can be set (0-365 days).
    • Redirection to URLs not containing the web base URL disables attribution.
    • Anonymous IP filtering is used for fraud prevention.
    • S2S events can be sent using adid or web_uuid.

  3. Testing & Troubleshooting

    • If you don't see data, double-check integration and dashboard settings.
    • For attribution and event tracking, use the API and monitor logs.

Always test on a fresh device/environment and monitor logs for real-time feedback. For persistent issues, consult the official documentation or contact AdTrace support.