Capacitor SDK Installation

Get started with the DoorstepAI Capacitor SDK to add intelligent delivery tracking to any Capacitor application.

Framework-Agnostic

The DoorstepAI Capacitor SDK works with any web framework that Capacitor supports — Angular, React, Vue, Next.js, Svelte, plain HTML, etc. The code snippets in these docs are written in Next.js / TypeScript for concreteness, but the SDK API is identical across frameworks. Translate the import statements and lifecycle hooks to your framework's idioms (e.g. ngOnInit in Angular, onMounted in Vue).

Prerequisites

Before you begin, ensure you have:

• Capacitor 5.0 or later integrated with your web framework
• Node.js 18+ and npm or yarn
• Valid API Key from DoorstepAI
• iOS 15+ deployment target for iOS
• Android API 24+ for Android

Development Environment

We recommend using the latest stable version of Capacitor for the best development experience. Capacitor needs a directory of static web assets (HTML/JS/CSS) produced by your framework's build to bundle into the native shell.

Installation

1. Add Dependencies

Install the DoorstepAI Capacitor SDK in your project:

npm install @doorstepai/dropoff-capacitor
# or
yarn add @doorstepai/dropoff-capacitor

2. Configure Capacitor

Capacitor needs to know where your framework writes its built static assets. Point webDir at that directory in capacitor.config.ts (or capacitor.config.json):

capacitor.config.ts

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.yourapp.package',
  appName: 'YourApp',
  webDir: 'out', // 👈 your framework's build output directory
};

export default config;

Common webDir values:

Framework	Default webDir
Next.js (static export)	out
Angular	dist/<project-name>
React (Vite)	dist
Create React App	build
Vue / Nuxt	dist

Next.js Specifics

If you are using Next.js, set output: 'export', images.unoptimized: true, and trailingSlash: true in next.config.js so the framework emits a fully static out/ directory that Capacitor can bundle. Other frameworks already produce static output by default.

3. Build & Sync Native Projects

Build your web app and sync the plugin into your native iOS and Android projects:

npm run build      # produces static assets in webDir
npx cap sync       # copies them into ios/ and android/ and links plugins

4. Platform-Specific Setup

iOS Setup

For iOS, install CocoaPods dependencies:

cd ios/App && pod install && cd ../..

Android Setup

For Android, the SDK is automatically linked via Capacitor's plugin registration—no additional manual steps are required.

Platform-Specific Configuration

iOS Configuration

Update your iOS app's Info.plist file with the required permissions:

ios/App/App/Info.plist

<dict>
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>This app requires access to your location for enhanced delivery intelligence</string>

    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>This app requires access to your location for enhanced delivery intelligence</string>

    <key>NSMotionUsageDescription</key>
    <string>This app requires access to motion data for enhanced delivery intelligence</string>

    <key>UIBackgroundModes</key>
    <array>
        <string>location</string>
    </array>
</dict>

Android Configuration

Update your Android app's AndroidManifest.xml file with the required permissions:

android/app/src/main/AndroidManifest.xml

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

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

    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

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

    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />

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

    <uses-feature android:name="android.hardware.sensor.accelerometer" />
    <uses-feature android:name="android.hardware.sensor.gyroscope" />
    <uses-feature android:name="android.hardware.sensor.barometer" />
    <uses-feature android:name="android.hardware.sensor.compass" />
    <uses-feature android:name="android.hardware.sensor.proximity" />

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

Permission Requirements

Permission	Purpose	Platform	Runtime Required
ACCESS_FINE_LOCATION	Precise location tracking	Android	✅ Yes
ACCESS_COARSE_LOCATION	Approximate location	Android	✅ Yes
ACCESS_BACKGROUND_LOCATION	Background location access	Android	✅ Yes
ACTIVITY_RECOGNITION	Motion and activity detection	Android	✅ Yes
FOREGROUND_SERVICE	Background processing	Android	❌ No
FOREGROUND_SERVICE_LOCATION	Location foreground service	Android	❌ No
FOREGROUND_SERVICE_DATA_SYNC	Data sync foreground service	Android	❌ No
POST_NOTIFICATIONS	Delivery notifications	Android	✅ Yes (API 33+)
WAKE_LOCK	Keep device awake during tracking	Android	❌ No
ACCESS_WIFI_STATE	WiFi state access	Android	❌ No
ACCESS_NETWORK_STATE	Network state access	Android	❌ No
INTERNET	Network communication	Android	❌ No
NSLocationWhenInUseUsageDescription	Location access during app usage	iOS	✅ Yes
NSLocationAlwaysAndWhenInUseUsageDescription	Background location access	iOS	✅ Yes
NSMotionUsageDescription	Motion and sensor data	iOS	✅ Yes

NOTIFICATION PERMISSION (ANDROID 13+)

Starting with Android 13 (API level 33), apps must request the POST_NOTIFICATIONS permission at runtime.

Verification

To verify the installation was successful:

1. Build and run your project:

   # Build your framework's static assets
   npm run build
   
   # Sync to native projects
   npx cap sync
   
   # iOS
   npx cap run ios
   
   # Android
   npx cap run android

2. Check for import errors in files using the SDK

3. Verify permissions are properly configured in platform-specific files

Import Test

Import the plugin from any module that runs in the browser after the app boots. The example below is Next.js; the equivalent in Angular would be importing DoorstepAI from a component class and logging inside ngOnInit.

Next.js example — app/page.tsx

'use client';

import { useEffect } from 'react';
import { DoorstepAI } from '@doorstepai/dropoff-capacitor';

export default function Home() {
  useEffect(() => {
    console.log('DoorstepAI plugin loaded:', !!DoorstepAI);
  }, []);

  return <main>doorstep.ai test</main>;
}

Runs in the Browser Only

The DoorstepAI plugin is a native bridge — it can only be called from code that runs in the WebView after Capacitor bootstraps. Don't call it during server-side rendering, pre-rendering, or build-time static generation.

Framework-specific guidance:

• Next.js / React Server Components: import from 'use client' modules only — never from Server Components or Route Handlers.
• Angular: call from component lifecycle hooks (ngOnInit, ngAfterViewInit) — not from APP_INITIALIZER factories that run before the platform is ready.
• Vue / Nuxt: call from onMounted — not from setup() running on the server.
• Any SSR framework: guard with Capacitor.isNativePlatform() or a platform check.

If you encounter any issues during installation, check our troubleshooting guide or contact our support team.

Next Steps

Now that you have the SDK installed and configured:

1. 📚 Learn SDK Usage - Initialize and use the SDK
2. 💡 View Examples - See complete implementation examples

info

For support and questions, contact us at support@doorstep.ai