BoostLinks Troubleshooting

This guide covers common issues you might encounter when setting up BoostLinks with BoostOps and how to resolve them.

iOS Universal Links Issues

BoostLink Opens Safari Instead of App

Symptoms:

BoostLink opens in Safari instead of your app
Works on some devices but not others
Worked before but stopped working

Solutions:

Check Associated Domains Configuration

In Unity → Player Settings → iOS → Configuration
Verify Associated Domains includes: applinks:yourdomain.com

Verify apple-app-site-association File
- Test your file directly: https://yourdomain.com/.well-known/apple-app-site-association
- Should return JSON content, not an error page
- Must be served over HTTPS with valid certificate
Check Bundle Identifier
- Ensure your iOS Bundle ID matches exactly what’s in your AASA file
- Case-sensitive match required

Clear iOS Cache

On device: Settings → General → iPhone Storage → [Your App] → Offload App
Reinstall the app to refresh BoostLinks cache

Test with Apple’s Validator
- Use Apple’s App Site Association validator
- Check for any warnings or errors

BoostLinks Work in Some Apps But Not Others

Symptoms:

BoostLinks work from Safari but not Messages
Work from some apps but not others
Inconsistent behavior across platforms

Solutions:

Check Smart App Banner Navigation
- If user previously tapped the Safari smart banner’s “Cancel” button
- iOS remembers this preference and stops opening the app
- Solution: Clear Safari history or test on different device
Verify HTTPS Certificate
- Must be valid, trusted certificate
- Self-signed certificates won’t work for BoostLinks
- Test certificate with online SSL checkers

Test Different Link Formats

Try these variations:
https://yourdomain.com/level/1
https://yourdomain.com/level/1/
https://yourdomain.com/level/1?param=value

App Crashes on BoostLink

Symptoms:

App opens but immediately crashes
Crashes only when opened via BoostLink
Works fine when opened normally

Solutions:

Check BoostLink Handling Code

// Add null checks and exception handling
void HandleBoostLink(string url) {
    try {
        if (string.IsNullOrEmpty(url)) return;

        // Your BoostLink parsing logic here
        Debug.Log($"Processing BoostLink: {url}");

    } catch (Exception e) {
        Debug.LogError($"BoostLink error: {e.Message}");
        // Fallback to main menu
        ShowMainMenu();
    }
}

Verify Scene Loading
- Ensure the scene/content referenced in the BoostLink exists
- Add validation before attempting to load content
Check for Memory Issues
- BoostLinks might trigger content loading before app is fully initialized
- Add initialization checks before processing BoostLinks

Android App Links Issues

BoostLinks Don’t Auto-Verify

Symptoms:

Android shows “Open with” dialog
BoostLinks don’t automatically open your app
Auto-verification fails

Solutions:

Verify Certificate Fingerprint

# Get your certificate fingerprint
keytool -list -v -keystore your-release-key.keystore

# Must match the fingerprint in your assetlinks.json

Check assetlinks.json File
- Test directly: https://yourdomain.com/.well-known/assetlinks.json
- Must be valid JSON
- Must include correct package name and fingerprint

Test Auto-Verification

# Use Google's testing tool
adb shell am start -W -a android.intent.action.VIEW -d "https://yourdomain.com/test" com.yourpackage.name

Check Android Manifest
- Verify android:autoVerify="true" is set
- Ensure intent-filter includes both http and https schemes

BoostLinks Work on Some Android Versions But Not Others

Symptoms:

Works on Android 12+ but not earlier versions
Different behavior across Android versions
Verification status varies by device

Solutions:

Check Android Version Compatibility
- Android 6.0+ required for App Links
- Different verification processes for different versions

Test Legacy Intent Filters

<!-- Add fallback intent filter -->
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="yourdomain.com" />
</intent-filter>

Verify Digital Asset Links
- Use Google’s Statement List Generator
- Test on different Android versions

BoostLinks Not Working After App Update

Symptoms:

Worked before app update
Now shows “Open with” dialog
Verification seems to reset

Solutions:

Re-verify After Updates
- Android re-checks verification after app updates
- May need to wait for re-verification process
Check for Manifest Changes
- Verify no intent-filter changes in the update
- Ensure package name hasn’t changed
Test Fresh Install
- Uninstall and reinstall the app
- This triggers fresh verification

General Issues

BoostLinks Work on Test Devices But Not Production

Symptoms:

Perfect behavior during testing
Issues reported by real users
Inconsistent behavior in production

Solutions:

Check Production Certificate
- Verify production certificate fingerprint matches assetlinks.json
- Test with actual production builds
Test Real Network Conditions
- Slow networks might affect verification
- Test with different network conditions
Monitor DNS and CDN
- Ensure your domain is accessible globally
- Check CDN configuration for .well-known files

BoostLinks Stop Working After Domain Changes

Symptoms:

Worked with old domain
New domain doesn’t trigger app opening
Users report BoostLinks broken

Solutions:

Update All Configuration Files
- Update apple-app-site-association
- Update assetlinks.json
- Update app manifest and iOS settings

Plan Migration Strategy

// Support both old and new domains temporarily
void HandleBoostLink(string url) {
    if (url.Contains("olddomain.com")) {
        // Redirect to new domain logic
        string newUrl = url.Replace("olddomain.com", "newdomain.boostlink.me");
        ProcessBoostLink(newUrl);
    } else {
        ProcessBoostLink(url);
    }
}

Update App Store Listings
- Update associated website URLs
- Update app descriptions if needed

Debugging Tools

iOS Debugging

Device Console
- Check for BoostLinks-related messages
- Look for domain verification errors

Xcode Debugging

Window → Devices and Simulators → [Your Device] → Console
Filter for "swcd" to see BoostLinks activity

Apple’s Validator
- Use Apple’s App Site Association validator
- Check branch.io’s AASA validator

Android Debugging

ADB Commands

# Check verification status
adb shell dumpsys package domain-preferred-apps

# Test specific BoostLink
adb shell am start -W -a android.intent.action.VIEW -d "https://yourdomain.com/test"

Logcat Monitoring

# Monitor for intent resolution
adb logcat | grep -i "intent"

Google’s Testing Tools
- Use Google’s Statement List Generator
- Test with Digital Asset Links API

BoostOps Managed BoostLinks Issues

Free Subdomain Not Working

Symptoms:

<app>.boostlink.me domain not resolving
BoostLinks not opening app
DNS or certificate errors

Solutions:

Verify Account Setup
- Ensure you’re signed in to BoostOps
- Check that your project is properly configured
- Verify domain has been provisioned

Test Domain Resolution

# Test if domain resolves
nslookup your-app.boostlink.me

# Test HTTPS certificate
curl -I https://your-app.boostlink.me/.well-known/apple-app-site-association

Check Configuration Sync
- Re-deploy configuration from Unity
- Verify all settings match in dashboard
- Check for any error messages in BoostOps console

Getting Help

BoostOps Support

Discord: Join our developer community
Email: support@boostops.com
Documentation: Complete BoostLinks Guide

Platform-Specific Help

iOS: Apple’s Universal Links Documentation
Android: Google’s App Links Documentation

Community Resources

Unity Forums: Unity deep linking discussions
Stack Overflow: Search for “BoostLinks” or “Universal Links” + your specific issue
Reddit: r/Unity3D and r/gamedev communities

Advanced Debugging

Testing Specific BoostLink Formats

Test these common patterns to identify issues:

# Basic path
https://your-app.boostlink.me/level/1

# With parameters
https://your-app.boostlink.me/store/item?id=123

# Nested paths
https://your-app.boostlink.me/game/level/boss-battle

# Campaign tracking
https://your-app.boostlink.me/invite/friend?ref=campaign123

Network Debugging

If BoostLinks work locally but not for users:

Test from Different Networks
- WiFi vs cellular
- Different ISPs
- Different countries/regions
Check CDN and Caching
- Verify files are cached globally
- Test cache invalidation
- Monitor edge server responses

Still having issues? Don’t hesitate to reach out to our support team. We’re here to help you get BoostLinks working perfectly in your game.