Troubleshooting

Common issues and solutions when integrating AttributeHQ.

Events Not Sending

Symptoms: Events are tracked in the SDK but never appear in the dashboard.

1. Check initialization — All tracking methods are no-ops before init() / initialize(). Enable debug logging to see warnings.

2. Check API key — Verify the key starts with ak_ and matches an active key in your dashboard.

3. Check network — Events are queued offline and retried. Open DevTools (Web) or device logs (mobile) to check for HTTP errors.

4. Check batching — Events are batched, not sent immediately. Wait for flushInterval (default: 5 seconds) or call flush() manually.

// Enable debug mode
init({ apiKey: '...', appId: '...', debug: true })
 
// Force flush
flush()
 
// Check DevTools Network tab for /api/v1/events

// Enable debug mode
let config = AttributeHQConfiguration(
    apiKey: "...", appId: "...",
    enableDebugLogging: true
)
// Check Xcode console for AttributeHQ logs

// Enable debug mode
val config = AttributeHQConfiguration(
    apiKey = "...", appId = "...",
    enableDebugLogging = true
)
// Check Logcat for AttributeHQ logs

// Enable debug mode
await AttributeHQ.initialize({
  apiKey: '...', appId: '...',
  enableDebugLogging: true,
})
// Check Metro console for native logs

Install Not Tracked

Symptoms: First launch doesn’t show an install in the dashboard.

1. Web: Check if __ahq_installed exists in localStorage. If so, the install was already tracked. Clear it and refresh to re-trigger.
2. Mobile: The install is tracked on first initialize() call. Check debug logs for the install request and response.
3. Check the API response — Look for POST /api/v1/installs in the network logs. A 201 response means it was tracked successfully.

Attribution Returns Organic

Symptoms: All installs show as “organic” even when coming from ad clicks.

1. Check click tracking — Verify your ad campaign links use the correct click URL format:

   https://api.attributehq.com/v1/clicks?app_id=YOUR_APP_ID&c=campaign&pid=source

2. Check attribution window — Clicks expire after 7 days. If the install happens after the window, it’s classified as organic.

3. Check device ID — For deterministic matching, ensure the SDK has access to IDFA (iOS) or GAID (Android). On iOS, ATT must be authorized.

4. Check CTIT — Installs within 10 seconds of a click are rejected as fraud. This is expected behavior.

Page Views Not Tracking in SPA (Web)

The Web SDK patches history.pushState and history.replaceState to detect navigation. If your framework uses a different mechanism:

// Manual page view tracking
import { trackPageView } from '@attributehq/web-sdk'
 
// In your router's navigation callback
router.afterEach(() => {
  trackPageView()
})

“SDK Not Initialized” Warning

All tracking methods check for initialization. If you see this warning:

• Web: Ensure init() is called before any track() calls. In frameworks like Next.js, use useEffect.
• React Native: initialize() is async — you must await it before calling other methods.
• Mobile: Ensure initialize() is called in Application.onCreate (Android) or AppDelegate.didFinishLaunching (iOS).

CORS Errors (Web)

If you see CORS errors in the browser console:

1. The API server (https://api.attributehq.com) allows all origins by default
2. Check that your request URL matches the expected API endpoint
3. Verify no browser extensions are blocking cross-origin requests

React Native: Native Module Not Linked

If you see: "AttributeHQ native module is not linked. Please install..."

1. Standard RN: Run cd ios && pod install && cd .. then rebuild
2. Expo: This SDK does not work in Expo Go. Use eas build instead
3. Autolinking: React Native 0.60+ autolinks native modules. If not working, run npx react-native link @attributehq/react-native-sdk

Duplicate Installs

The SDK uses idempotency to prevent duplicate installs:

• Same device_id: Returns cached attribution result
• Web: Checks __ahq_installed in localStorage

If you’re seeing duplicates, check that device_id is consistent across app launches.

High Organic Rate

If your organic rate is unexpectedly high:

1. IDFA availability — On iOS 14+, most users deny ATT. Without IDFA, attribution relies on fingerprinting (lower match rate)
2. Ad network integration — Ensure your ad campaigns use AttributeHQ click URLs, not direct app store links
3. Fingerprint accuracy — Users on the same network (e.g., corporate WiFi) may share IP addresses, reducing fingerprint uniqueness