UserAnalyticsSDK

Troubleshooting Guide

Common issues and solutions for the User Analytics SDK.

🚨 Common Issues

Installation Problems

“Could not resolve dependency”

Error Message:

Could not resolve: com.github.nSella10:UserAnalyticsSDK:v1.0.6

Solutions:

1. Check JitPack Repository

   // In settings.gradle
   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
           maven { url 'https://jitpack.io' } // Make sure this is present
       }
   }
   

2. Clear Gradle Cache

   ./gradlew clean
   ./gradlew build --refresh-dependencies
   

3. Check Internet Connection
   • Ensure your development machine has internet access
   • Try building with VPN disabled if using one
4. Verify Version
   • Check JitPack page for available versions
   • Use latest stable version: v1.0.6

“Manifest merger failed”

Error Message:

Manifest merger failed : uses-permission#android.permission.INTERNET was tagged at AndroidManifest.xml

Solution:

<!-- Remove duplicate INTERNET permissions -->
<uses-permission android:name="android.permission.INTERNET" />

Runtime Errors

“API Key not initialized”

Error Message:

❌ API Key not initialized. Call init() first.

Solutions:

1. Initialize SDK First

   // Call this before any other SDK methods
   AnalyticsTracker.init("https://d1xb34m3k0zeus.cloudfront.net/", "your_api_key");
   

2. Check Initialization Location

   // Initialize in onCreate() of your main activity
   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
          
       // Initialize here
       AnalyticsTracker.init("https://d1xb34m3k0zeus.cloudfront.net/", "ak_your_key");
   }
   

“Network error”

Error Message:

❌ Network error sending event: java.net.UnknownHostException

Solutions:

1. Check Internet Permission

   <uses-permission android:name="android.permission.INTERNET" />
   

2. Verify Network Connection
   • Test on device with internet access
   • Check if emulator has network access
3. Check Server URL

   // Use correct server URL
   AnalyticsTracker.init("https://d1xb34m3k0zeus.cloudfront.net/", "your_api_key");
   

4. Network Security Config

   <!-- In AndroidManifest.xml -->
   <application
       android:networkSecurityConfig="@xml/network_security_config">
   

   <!-- res/xml/network_security_config.xml -->
   <?xml version="1.0" encoding="utf-8"?>
   <network-security-config>
       <domain-config cleartextTrafficPermitted="false">
           <domain includeSubdomains="true">d1xb34m3k0zeus.cloudfront.net</domain>
       </domain-config>
   </network-security-config>
   

“Invalid API Key”

Error Message:

❌ Event failed with code: 401

Solutions:

1. Verify API Key Format
   • Should start with ak_
   • Example: ak_827aeb412aed4b23b8260432
2. Check Dashboard
   • Log into Developer Dashboard
   • Verify API key is correct
   • Ensure app is active
3. Copy-Paste Carefully

   // Avoid typos - copy directly from dashboard
   String apiKey = "ak_827aeb412aed4b23b8260432"; // Your actual key
   AnalyticsTracker.init("https://d1xb34m3k0zeus.cloudfront.net/", apiKey);
   

Data Not Appearing

Events not showing in dashboard

Possible Causes:

1. Wrong App Selected
   • Check you’ve selected correct app in dashboard
   • Verify API key matches selected app
2. Timing Issues
   • Data appears within seconds, but check after 1-2 minutes
   • Refresh dashboard page
3. Event Not Sent

   // Check logs for confirmation
   Log.d("AnalyticsTracker", "Event sent successfully");
   

4. User ID Issues

   // Ensure user ID is not null or empty
   String userId = UserManager.getCurrentUserId();
   if (userId != null && !userId.isEmpty()) {
       AnalyticsTracker.trackEvent(userId, "event_name", properties);
   }
   

Screen time not tracking

Solutions:

1. Pair Start/End Calls

   @Override
   protected void onResume() {
       super.onResume();
       AnalyticsTracker.startScreen("MainActivity");
   }
   
   @Override
   protected void onPause() {
       super.onPause();
       AnalyticsTracker.endScreen("user123");
   }
   

2. Check User ID

   // Use same user ID for start and end
   private String userId = UserManager.getCurrentUserId();
      
   AnalyticsTracker.startScreen("MainActivity");
   // Later...
   AnalyticsTracker.endScreen(userId); // Same user ID
   

Performance Issues

App feels slow after SDK integration

Solutions:

1. SDK is Async
   • All network calls are asynchronous
   • SDK doesn’t block UI thread
2. Reduce Event Frequency

   // Don't track every scroll event
   private long lastScrollTrack = 0;
      
   private void onScroll() {
       long now = System.currentTimeMillis();
       if (now - lastScrollTrack > 5000) { // 5 second throttle
           trackScrollEvent();
           lastScrollTrack = now;
       }
   }
   

3. Batch Events

   // Instead of tracking every click, batch them
   private List<String> clickEvents = new ArrayList<>();
      
   private void onButtonClick(String buttonName) {
       clickEvents.add(buttonName);
          
       // Send batch every 10 clicks
       if (clickEvents.size() >= 10) {
           sendBatchedEvents();
           clickEvents.clear();
       }
   }
   

🔧 Debug Mode

Enable Detailed Logging

// Add this to see detailed SDK logs
if (BuildConfig.DEBUG) {
    // SDK automatically logs to Android Log
    // Filter by "AnalyticsTracker" tag in Logcat
}

Logcat Filters

# View only SDK logs
adb logcat -s AnalyticsTracker

# View network logs
adb logcat -s AnalyticsTracker,OkHttp

Test Events

// Send test event to verify connection
Map<String, Object> testProps = new HashMap<>();
testProps.put("test", true);
testProps.put("timestamp", System.currentTimeMillis());
AnalyticsTracker.trackEvent("test_user", "sdk_test", testProps);

🧪 Testing Checklist

Before Release

• SDK initializes without errors
• Test events appear in dashboard
• Screen time tracking works
• No network errors in logs
• App performance not affected
• API key is secure (not hardcoded)

Test Scenarios

1. Fresh Install

   // Test with new user ID
   String newUserId = UUID.randomUUID().toString();
   AnalyticsTracker.trackEvent(newUserId, "first_launch", properties);
   

2. Network Interruption
   • Turn off WiFi during event sending
   • Verify events are queued and sent when connection returns
3. App Backgrounding

   // Test screen time tracking with app switching
   // onPause() -> onResume() cycle
   

📞 Getting Help

Self-Help Resources

1. Check Logs First

   adb logcat -s AnalyticsTracker
   

2. Verify Configuration
   • API key format and validity
   • Network permissions
   • Server URL
3. Test with Minimal Example

   // Minimal test case
   AnalyticsTracker.init("https://d1xb34m3k0zeus.cloudfront.net/", "your_api_key");
      
   Map<String, Object> props = new HashMap<>();
   props.put("test", "minimal");
   AnalyticsTracker.trackEvent("test_user", "test_event", props);
   

Contact Support

If issues persist:

1. GitHub Issues
   • Create new issue
   • Include error logs and code snippets
2. Information to Include
   • Android version
   • SDK version
   • Error logs
   • Minimal reproduction code
   • Device/emulator details

Known Issues

Android 9+ Network Security

Issue: Network requests blocked on Android 9+

Solution:

<!-- Add to AndroidManifest.xml -->
<application
    android:usesCleartextTraffic="false"
    android:networkSecurityConfig="@xml/network_security_config">

ProGuard/R8 Obfuscation

Issue: SDK classes obfuscated in release builds

Solution:

# Add to proguard-rules.pro
-keep class com.analytics.analyticstracker.** { *; }
-keep interface com.analytics.analyticstracker.** { *; }

🔄 Version Migration

Upgrading from v1.0.5 to v1.0.6

No breaking changes - just update version:

implementation 'com.github.nSella10:UserAnalyticsSDK:v1.0.6'

Future Upgrades

Check CHANGELOG.md for version-specific migration notes.

---

Still having issues? Open an issue on GitHub

This site is open source. Improve this page.