Android SDK Installation

Get started with the DoorstepAI Android SDK to add intelligent delivery tracking to your Android application.

Prerequisites

Before you begin, ensure you have:

• Android Studio (latest stable version recommended)
• Minimum SDK version: Android API level 21 (Android 5.0)
• Target SDK version: Android API level 33+ (Android 13+)
• Valid API Key from DoorstepAI
• Kotlin or Java development environment

Development Environment

We recommend using Android Studio with the latest Android Gradle Plugin for the best development experience and access to the latest Android features.

Installation

Add SDK Dependency

Add the DoorstepAI Android SDK to your module-level build.gradle file (usually app/build.gradle):

app/build.gradle

dependencies {
    implementation 'ai.doorstep.com:doorstepai-dropoff-sdk:2.2.2'
    
    // Other dependencies...
}

The DoorstepPermission whitelist API requires 2.2.1 or newer; route events gained serverSessionId in 2.2.2.

Sync Project

After adding the dependency, sync your project:

1. Click "Sync Now" in the notification bar, or
2. Go to File → Sync Project with Gradle Files

Android Manifest Configuration

Required Permissions

The SDK's library manifest supplies its service, receiver, provider, and every SDK permission except INTERNET. Android's manifest merger adds those declarations to your app at build time. Add INTERNET outside the <application> tag or session uploads cannot run:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.yourapp.package">

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

    <application>
        <!-- Your app components -->
    </application>
</manifest>

The merged SDK manifest contributes:

• Runtime permissions: coarse/fine/background location, activity recognition, Bluetooth scan, nearby Wi-Fi devices, and notifications.
• Install-time permissions: foreground service, foreground-service location, wake lock, network and Wi-Fi state, Wi-Fi state changes, boot completed, legacy Bluetooth compatibility, and battery optimization settings access.
• android.hardware.wifi.rtt as an optional feature (required="false"). The SDK does not require accelerometer, gyroscope, barometer, compass, or proximity hardware at install time, so do not add required sensor <uses-feature> declarations unless your own app needs them.

Use Android Studio's Merged Manifest view to review the exact result for your build and reconcile it with Play Console declarations.

Permission Details

Permission	Runtime
INTERNET	No
ACCESS_FINE_LOCATION	Yes
ACCESS_COARSE_LOCATION	Yes
ACCESS_BACKGROUND_LOCATION	Yes — separate, second request after foreground location is granted (Android 11+ auto-denies a bundled ask)
ACTIVITY_RECOGNITION	Yes (API 29+)
BLUETOOTH_SCAN	Yes (API 31+)
NEARBY_WIFI_DEVICES	Yes (API 33+)
FOREGROUND_SERVICE	No
FOREGROUND_SERVICE_LOCATION	No
POST_NOTIFICATIONS	Yes (API 33+)
WAKE_LOCK	No
ACCESS_WIFI_STATE	No
ACCESS_NETWORK_STATE	No

Notification Permission (Android 13+)

Starting with Android 13 (API level 33), apps must request the POST_NOTIFICATIONS permission at runtime. Users must explicitly grant notification permission for the SDK to show delivery tracking notifications.

Requesting Permissions at Runtime

Only the rows marked Runtime = Yes above are ever requested at runtime. ACCESS_NETWORK_STATE, FOREGROUND_SERVICE*, WAKE_LOCK and ACCESS_WIFI_STATE are install-time (normal) permissions — the OS grants them when your app is installed, and they must never appear in a runtime permission request.

No helper class needed: the SDK ships the API. DoorstepAI.checkPermissions(...) observes state and never prompts; DoorstepAI.requestPermissions(activity, setOf(...)) asks for exactly the buckets you name; DoorstepAI.requestAllPermissions(activity) asks for all of them.

MainActivity.kt

import com.doorstepai.sdks.tracking.DoorstepAI
import com.doorstepai.sdks.tracking.DoorstepPermission
import com.doorstepai.sdks.tracking.DoorstepPermissionState

val foreground = DoorstepAI.checkPermission(this, DoorstepPermission.LOCATION_WHEN_IN_USE)
if (foreground.state == DoorstepPermissionState.GRANTED) {
    // Background location is always its OWN, second request.
    DoorstepAI.requestPermissions(this, setOf(DoorstepPermission.LOCATION_ALWAYS))
} else {
    DoorstepAI.requestPermissions(this, setOf(DoorstepPermission.LOCATION_WHEN_IN_USE))
}

Pass a whitelist, or call requestAllPermissions

While the deprecated includeBluetooth overload still exists, a bare DoorstepAI.requestPermissions(activity) is an overload-resolution ambiguity and will not compile. Use DoorstepAI.requestAllPermissions(activity) or always pass an explicit whitelist.

Full reference — buckets, states, forwarding results with DoorstepAI.notePermissionRequestResult(...), and the recommended staged permission flow: Permissions.

Verification

To verify the installation was successful:

1. Build your project (Build → Rebuild Project)
2. Check for import errors in files using DoorstepAI SDK classes
3. Verify permissions are properly declared in your AndroidManifest.xml

Import Test

Try importing the SDK and calling init to sanity-check the build. See Using the SDK → Initialize SDK for the full initialization flow:

MainActivity.kt

import com.doorstepai.sdks.tracking.DoorstepAI

DoorstepAI.init(this) { result ->
    result.fold(
        onSuccess = { DoorstepAI.setAPIKey("your_api_key_here") },
        onFailure = { error -> /* handle error */ }
    )
}

Troubleshooting Installation

Common Issues

Build Errors

• Error: "Could not resolve dependency"
  • Solution: Check internet connection and verify the repository URL
  • Solution: Ensure you're using the correct version number

Manifest Merge Conflicts

See the detailed troubleshooting guide in Examples for manifest merger errors.

Permission Issues

• A permission reports NOT_DECLARED: the permission was removed or otherwise lost during manifest merge. Inspect the merged manifest, restore the declaration, and rebuild. It is not a user refusal.
• The background-location request is denied instantly: it was bundled with the foreground ask. ACCESS_BACKGROUND_LOCATION must be a separate, second request made only after foreground location is granted.
• A denial can't be told from a permanent one: forward onRequestPermissionsResult to DoorstepAI.notePermissionRequestResult(...).

Full list of symptoms and fixes: Permissions → Troubleshooting.

Getting Help

If you encounter issues during installation:

1. Check our troubleshooting guide
2. Review the Android integration examples
3. Contact our support team at support@doorstep.ai

Next Steps

Now that you have the SDK installed and configured:

1. 📚 Learn SDK Usage - Initialize and use the SDK
2. 🔐 Review Permissions - Implement staged runtime requests
3. 💡 View Examples - See complete implementation examples

Ready to Implement?

Head over to our Usage Guide to learn how to implement the SDK and start using delivery tracking in your Android app.