Despia SDK

https://www.npmjs.com/package/despia-native
Admin
The Despia SDK is a JavaScript library that allows React, Vue, Angular, and other web apps to access...
Tokens:86,214
Snippets:626
Trust Score:9.6
Update:9 months ago
Show doc for...
Tokens:
Raw
### Biometric Authentication Setup and Execution with Despia

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependents

This example demonstrates setting up and triggering biometric authentication using Despia. It involves dynamically adding a script tag for the biometric SDK, defining callback functions for success, failure, and unavailability, and then initiating the authentication process via a Despia command. Dependencies include the Despia SDK and a compatible biometric authentication SDK.

```javascript
// Step 1: Set up the biometric authentication SDK
if (!document.getElementById("bioauth-sdk")) {
    const script = document.createElement("script")
    script.id = "bioauth-sdk"
    script.type = "text/javascript"
    script.textContent = `
        function onBioAuthSuccess() {
            window.bioauthSuccess()
        }
        function onBioAuthFailure(errorCode, errorMessage) {
            window.bioauthFailure(errorCode, errorMessage)
        }
        function onBioAuthUnavailable() {
            window.bioauthUnavailable()
        }
    `
    document.head.appendChild(script)
}

// Step 2: Define your callback functions
window.bioauthSuccess = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication successful");
        // Handle successful authentication
        // Redirect user, unlock features, etc.
    }
}

window.bioauthFailure = function(errorCode, errorMessage) {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication failed:", errorCode, errorMessage);
        // Handle authentication failure
        // Show error message, fallback to password, etc.
    }
}

window.bioauthUnavailable = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication unavailable");
        // Handle when biometric auth is not available
        // Fallback to alternative authentication method
    }
}

// Step 3: Trigger biometric authentication
despia('bioauth://');
```

--------------------------------

### Despia Protocol Command Examples

Source: https://www.npmjs.com/package/despia-native/v/1.0

Illustrates the general format and provides examples of Despia protocol commands used to invoke native features. The format is `feature://action?parameters`. These commands are sent via the `window.despia` object.

```plaintext
feature://action?parameters

Examples:
  * `lighthaptic://`
  * `getappversion://`
  * `revenuecat://purchase?external_id=user_777&product=monthly_premium`
  * `requestcontactpermission://`
  * `savethisimage://?url=https://example.com/image.jpg
```

--------------------------------

### Despia Command Examples (TypeScript)

Source: https://www.npmjs.com/package/despia-native/index

Provides a comprehensive set of examples for various Despia commands, including native widgets, in-app purchases, permissions, location services, push notifications, haptic feedback, app information, file operations, UI controls, and sharing.

```typescript
// Native Widgets
despia('widget://${svg}?refresh=${refresh_time}');

// RevenueCat In-App Purchases
despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');

// Contact Permissions
despia('requestcontactpermission://');
const contacts = await despia('readcontacts://', ['contacts']);

// Background Location
despia('backgroundlocationon://');
// Use native browser geolocation API (not despia native runtime)
const watchId = navigator.geolocation.watchPosition(
  (position) => console.log('Location:', position),
  (error) => console.error('Location error:', error)
);
// To stop
despia('backgroundlocationoff://');
avigator.geolocation.clearWatch(watchId);

// Push Notifications
despia('registerpush://');
despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
const oneSignalData = await despia('getonesignalplayerid://', ['onesignalplayerid']);

// Haptic Feedback
despia('lighthaptic://');
despia('heavyhaptic://');
despia('successhaptic://');
despia('warninghaptic://');
despia('errorhaptic://');

// App Information
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceInfo = await despia('get-uuid://', ['uuid']);

// Screenshots and Scanning
despia('takescreenshot://');
despia('scanningmode://auto');
despia('scanningmode://on');
despia('scanningmode://off');

// Store and Location
const storeData = await despia('getstorelocation://', ['storeLocation']);

// Image and File Operations
despia('savethisimage://?url=${image_url}');
despia('file://${file_url}');

// App Control
despia('reset://');
const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);

// UI Controls
despia('spinneron://');
despia('spinneroff://');
despia('hidebars://on');
despia('hidebars://off');

// Sharing
despia('shareapp://message?=${message}&url=${url}');

// Status Bar Styling
despia('statusbarcolor://{255, 255, 255}');
despia('statusbartextcolor://{black}');

// Biometric Authentication
despia('bioauth://');

```

--------------------------------

### Despia Protocol Format Examples

Source: https://www.npmjs.com/package/despia-native/v/1.0_activeTab=readme

Illustrates the structure and examples of Despia protocol commands used for interacting with native features.

```APIDOC
## Despia Protocol Format

### Description
Despia uses a simple protocol format for all native integrations, following the pattern `feature://action?parameters`.

### Examples

- `lighthaptic://`
- `getappversion://`
- `revenuecat://purchase?external_id=user_777&product=monthly_premium`
- `requestcontactpermission://`
- `savethisimage://?url=https://example.com/image.jpg`
```

--------------------------------

### Examples of despia commands

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependents

A collection of quick examples showcasing various despia commands for haptic feedback, app information retrieval, UI control, and screenshot/sharing functionalities.

```javascript
// Haptic feedback
despia('lighthaptic://');    // Light vibration
despia('heavyhaptic://');    // Heavy vibration
despia('successhaptic://');  // Success vibration

// App information
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceId = await despia('get-uuid://', ['uuid']);

// UI controls
despia('spinneron://');      // Show loading
despia('spinneroff://');     // Hide loading
despia('hidebars://on');     // Hide status bar

// Screenshots and sharing
despia('takescreenshot://');
despia('shareapp://message?=Hello&url=https://myapp.com');
```

--------------------------------

### Despia Command Examples: Native Widgets, IAPs, Permissions

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependencies

Provides examples of various Despia commands, including native widget interaction, RevenueCat in-app purchases, requesting contact permissions, and reading contacts. Demonstrates how to pass parameters and handle responses.

```typescript
// Native Widgets
despia('widget://${svg}?refresh=${refresh_time}');

// RevenueCat In-App Purchases
despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');

// Contact Permissions
despia('requestcontactpermission://');
const contacts = await despia('readcontacts://', ['contacts']);
```

--------------------------------

### Despia Command Examples

Source: https://www.npmjs.com/package/despia-native/index_activeTab=versions

Provides a comprehensive list of example Despia protocol commands for various functionalities, including UI controls, permissions, notifications, and more.

```APIDOC
## Despia Command Examples

### Description
This section provides a catalog of example Despia protocol commands for interacting with various native device features and application functionalities. These examples cover a wide range of use cases, from UI manipulation and user authentication to data handling and system information retrieval.

### Method
`despia(protocolString: string, responseVariables?: string[])`

### Endpoint
N/A (SDK function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// Native Widgets
despia('widget://${svg}?refresh=${refresh_time}');

// RevenueCat In-App Purchases
despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');

// Contact Permissions
despia('requestcontactpermission://');
const contacts = await despia('readcontacts://', ['contacts']);

// Background Location
despia('backgroundlocationon://');
// Use native browser geolocation API (not despia native runtime)
const watchId = navigator.geolocation.watchPosition(
  (position) => console.log('Location:', position),
  (error) => console.error('Location error:', error)
);
// To stop
despia('backgroundlocationoff://');
navigator.geolocation.clearWatch(watchId);

// Push Notifications
despia('registerpush://');
despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
const oneSignalData = await despia('getonesignalplayerid://', ['onesignalplayerid']);

// Haptic Feedback
despia('lighthaptic://');
despia('heavyhaptic://');
despia('successhaptic://');
despia('warninghaptic://');
despia('errorhaptic://');

// App Information
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceInfo = await despia('get-uuid://', ['uuid']);

// Screenshots and Scanning
despia('takescreenshot://');
despia('scanningmode://auto');
despia('scanningmode://on');
despia('scanningmode://off');

// Store and Location
const storeData = await despia('getstorelocation://', ['storeLocation']);

// Image and File Operations
despia('savethisimage://?url=${image_url}');
despia('file://${file_url}');

// App Control
despia('reset://');
const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);

// UI Controls
despia('spinneron://');
despia('spinneroff://');
despia('hidebars://on');
despia('hidebars://off');

// Sharing
despia('shareapp://message?=${message}&url=${url}');

// Status Bar Styling
despia('statusbarcolor://{255, 255, 255}');
despia('statusbartextcolor://{black}');

// Biometric Authentication
despia('bioauth://');
```

### Response
Depends on the specific command executed. Some commands return `undefined`, while others may return specific data based on the requested `responseVariables`.
```

--------------------------------

### Install despia-native npm Package

Source: https://www.npmjs.com/package/despia-native/v/1.0

This command installs the despia-native npm package, which is the core JavaScript SDK for Despia.

```bash
npm install despia-native
```

--------------------------------

### Despia Protocol Format Example

Source: https://www.npmjs.com/package/despia-native/v/1.0_activeTab=dependencies

Demonstrates the basic structure of Despia's protocol format, which uses a `feature://action?parameters` scheme for invoking native functionalities. Examples include simple actions like `lighthaptic://` and more complex ones with parameters such as `revenuecat://purchase?external_id=user_777&product=monthly_premium`.

```text
feature://action?parameters

Examples:
  * `lighthaptic://`
  * `getappversion://`
  * `revenuecat://purchase?external_id=user_777&product=monthly_premium`
  * `requestcontactpermission://`
  * `savethisimage://?url=https://example.com/image.jpg`
```

--------------------------------

### Despia Protocol Format Example

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependencies

Illustrates the general format of Despia protocol commands, which follow a `feature://action?parameters` structure for interacting with native features.

```text
feature://action?parameters

Examples:
  * lighthaptic://
  * getappversion://
  * revenuecat://purchase?external_id=user_777&product=monthly_premium
  * requestcontactpermission://
  * savethisimage://?url=https://example.com/image.jpg
```

--------------------------------

### Biometric Authentication Setup and Trigger

Source: https://www.npmjs.com/package/despia-native/v/1.0

Enables biometric authentication by setting up necessary callback functions and then triggering the authentication process via the despia command. Requires prior SDK setup and definition of success, failure, and unavailable handlers.

```javascript
// Step 1: Set up the biometric authentication SDK
if (!document.getElementById("bioauth-sdk")) {
    const script = document.createElement("script")
    script.id = "bioauth-sdk"
    script.type = "text/javascript"
    script.textContent = "
        function onBioAuthSuccess() {
            window.bioauthSuccess()
        }
        function onBioAuthFailure(errorCode, errorMessage) {
            window.bioauthFailure(errorCode, errorMessage)
        }
        function onBioAuthUnavailable() {
            window.bioauthUnavailable()
        }
    "
    document.head.appendChild(script)
}

// Step 2: Define your callback functions
window.bioauthSuccess = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication successful");
        // Handle successful authentication
        // Redirect user, unlock features, etc.
    }
}

window.bioauthFailure = function(errorCode, errorMessage) {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication failed:", errorCode, errorMessage);
        // Handle authentication failure
        // Show error message, fallback to password, etc.
    }
}

window.bioauthUnavailable = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication unavailable");
        // Handle when biometric auth is not available
        // Fallback to alternative authentication method
    }
}

// Step 3: Trigger biometric authentication
despia('bioauth://');
```

--------------------------------

### Despia Command Examples: Sharing, Status Bar, Biometrics

Source: https://www.npmjs.com/package/despia-native/index_activeTab=readme

Provides examples of using despia-native for app sharing, customizing the status bar appearance, and initiating biometric authentication.

```typescript
// Sharing
despia('shareapp://message?=${message}&url=${url}');

// Status Bar Styling
despia('statusbarcolor://{255, 255, 255}');
despia('statusbartextcolor://{black}');

// Biometric Authentication
despia('bioauth://');
```

--------------------------------

### Despia Command Examples (TypeScript)

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependents

A collection of various Despia command examples covering a wide range of functionalities including widgets, in-app purchases, permissions, notifications, haptic feedback, app information, and UI controls.

```typescript
// Native Widgets
despia('widget://${svg}?refresh=${refresh_time}');

// RevenueCat In-App Purchases
despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');

// Contact Permissions
despia('requestcontactpermission://');
const contacts = await despia('readcontacts://', ['contacts']);

// Background Location
despia('backgroundlocationon://');
// Use native browser geolocation API (not despia native runtime)
const watchId = navigator.geolocation.watchPosition(
  (position) => console.log('Location:', position),
  (error) => console.error('Location error:', error)
);
// To stop
despia('backgroundlocationoff://');
navigator.geolocation.clearWatch(watchId);

// Push Notifications
despia('registerpush://');
despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
const oneSignalData = await despia('getonesignalplayerid://', ['onesignalplayerid']);

// Haptic Feedback
despia('lighthaptic://');
despia('heavyhaptic://');
despia('successhaptic://');
despia('warninghaptic://');
despia('errorhaptic://');

// App Information
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceInfo = await despia('get-uuid://', ['uuid']);

// Screenshots and Scanning
despia('takescreenshot://');
despia('scanningmode://auto');
despia('scanningmode://on');
despia('scanningmode://off');

// Store and Location
const storeData = await despia('getstorelocation://', ['storeLocation']);

// Image and File Operations
despia('savethisimage://?url=${image_url}');
despia('file://${file_url}');

// App Control
despia('reset://');
const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);

// UI Controls
despia('spinneron://');
despia('spinneroff://');
despia('hidebars://on');
despia('hidebars://off');

// Sharing
despia('shareapp://message?=${message}&url=${url}');

// Status Bar Styling
despia('statusbarcolor://{255, 255, 255}');
despia('statusbartextcolor://{black}');

// Biometric Authentication
despia('bioauth://');

```

--------------------------------

### Despia Command Examples: Store Location, File Operations, Tracking

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependencies

Covers Despia commands for fetching store location data, handling image saving and file access via URLs, and controlling user tracking preferences.

```typescript
// Store and Location
const storeData = await despia('getstorelocation://', ['storeLocation']);

// Image and File Operations
despia('savethisimage://?url=${image_url}');
despia('file://${file_url}');

// App Control
despia('reset://');
const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);
```

--------------------------------

### Despia Command Examples: App Info, Screenshots, Scanning

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependencies

Demonstrates Despia commands for retrieving application and device information, taking screenshots, and controlling scanning mode (auto, on, off).

```typescript
// App Information
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceInfo = await despia('get-uuid://', ['uuid']);

// Screenshots and Scanning
despia('takescreenshot://');
despia('scanningmode://auto');
despia('scanningmode://on');
despia('scanningmode://off');
```

--------------------------------

### Biometric Authentication Setup and Usage

Source: https://www.npmjs.com/package/despia-native/v/1.0_activeTab=dependencies

Sets up callback functions for biometric authentication and triggers the authentication process. Requires the Despia native runtime and specific user agent. Handles success, failure, and unavailability scenarios.

```javascript
// Step 1: Set up the biometric authentication SDK
if (!document.getElementById("bioauth-sdk")) {
    const script = document.createElement("script")
    script.id = "bioauth-sdk"
    script.type = "text/javascript"
    script.textContent = `
        function onBioAuthSuccess() {
            window.bioauthSuccess()
        }
        function onBioAuthFailure(errorCode, errorMessage) {
            window.bioauthFailure(errorCode, errorMessage)
        }
        function onBioAuthUnavailable() {
            window.bioauthUnavailable()
        }
    `
    document.head.appendChild(script)
}

// Step 2: Define your callback functions
window.bioauthSuccess = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication successful");
        // Handle successful authentication
        // Redirect user, unlock features, etc.
    }
}

window.bioauthFailure = function(errorCode, errorMessage) {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication failed:", errorCode, errorMessage);
        // Handle authentication failure
        // Show error message, fallback to password, etc.
    }
}

window.bioauthUnavailable = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication unavailable");
        // Handle when biometric auth is not available
        // Fallback to alternative authentication method
    }
}

// Step 3: Trigger biometric authentication
despia('bioauth://');

```

--------------------------------

### Using despia-native for Commands Returning Data

Source: https://www.npmjs.com/package/despia-native/index_activeTab=readme

Demonstrates how to use the despia function with commands that return data, using the `await` keyword. It shows examples for fetching app information and contacts.

```javascript
// Commands that return data (use await)
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
console.log(appInfo); // { versionNumber: '1.0.0', bundleNumber: '123' }

const contacts = await despia('readcontacts://', ['contacts']);
console.log(contacts); // { contacts: [...] }
```

--------------------------------

### Basic Despia Command Execution

Source: https://www.npmjs.com/package/despia-native/index

Demonstrates how to execute basic Despia protocol commands and how to execute commands that require waiting for response variables. It also provides examples for various command types.

```APIDOC
## Basic Despia Command Execution

### Description
This section details how to execute Despia protocol commands, including those that do not require a response and those that require asynchronous handling for response variables. It also provides specific examples of various Despia commands.

### Method
`despia(command: string, variables?: string[]) => Promise<any> | void`

### Endpoint
N/A (SDK function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import despia from 'despia-native';

// Execute a Despia protocol command (no response needed)
despia('lighthaptic://');

// Execute command and watch for response variables (await needed)
const result = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
console.log(result); // { versionNumber: '1.0.0', bundleNumber: '123' }
```

### Response
#### Success Response (200)
- `void`: If the command does not expect a response.
- `any`: If the command expects a response, the parsed response data is returned.

#### Response Example
```json
{
  "versionNumber": "1.0.0",
  "bundleNumber": "123"
}
```

### Despia Command Examples
```javascript
// Native Widgets
despia('widget://${svg}?refresh=${refresh_time}');

// RevenueCat In-App Purchases
despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');

// Contact Permissions
despia('requestcontactpermission://');
const contacts = await despia('readcontacts://', ['contacts']);

// Background Location
despia('backgroundlocationon://');
// Use native browser geolocation API (not despia native runtime)
const watchId = navigator.geolocation.watchPosition(
  (position) => console.log('Location:', position),
  (error) => console.error('Location error:', error)
);
// To stop
despia('backgroundlocationoff://');
navigator.geolocation.clearWatch(watchId);

// Push Notifications
despia('registerpush://');
despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
const oneSignalData = await despia('getonesignalplayerid://', ['onesignalplayerid']);

// Haptic Feedback
despia('lighthaptic://');
despia('heavyhaptic://');
despia('successhaptic://');
despia('warninghaptic://');
despia('errorhaptic://');

// App Information
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceInfo = await despia('get-uuid://', ['uuid']);

// Screenshots and Scanning
despia('takescreenshot://');
despia('scanningmode://auto');
despia('scanningmode://on');
despia('scanningmode://off');

// Store and Location
const storeData = await despia('getstorelocation://', ['storeLocation']);

// Image and File Operations
despia('savethisimage://?url=${image_url}');
despia('file://${file_url}');

// App Control
despia('reset://');
const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);

// UI Controls
despia('spinneron://');
despia('spinneroff://');
despia('hidebars://on');
despia('hidebars://off');

// Sharing
despia('shareapp://message?=${message}&url=${url}');

// Status Bar Styling
despia('statusbarcolor://{255, 255, 255}');
despia('statusbartextcolor://{black}');

// Biometric Authentication
despia('bioauth://');
```
```

--------------------------------

### Despia UI Control and Feedback Examples

Source: https://www.npmjs.com/package/despia-native/index_activeTab=versions

Provides quick examples of using Despia for UI interactions like showing/hiding spinners, controlling the status bar, and triggering different types of haptic feedback.

```javascript
// Haptic feedback
despia('lighthaptic://');    // Light vibration
despia('heavyhaptic://');    // Heavy vibration
despia('successhaptic://');  // Success vibration

// UI controls
despia('spinneron://');      // Show loading
despia('spinneroff://');     // Hide loading
despia('hidebars://on');     // Hide status bar
```

--------------------------------

### Native Widgets and Core Functionality

Source: https://www.npmjs.com/package/despia-native/v/1.0_activeTab=code

Examples of using Despia for native widgets, in-app purchases, and permission requests.

```APIDOC
## Native Widgets and Core Functionality

### Description
This section details how to use the Despia SDK for various native functionalities, including rendering widgets, handling in-app purchases, requesting permissions, and managing background services.

### Method
`despia(command, [responseKeys])`

### Endpoint
N/A (This is a client-side SDK function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
// Native Widgets
despia('widget://${svg}?refresh=${refresh_time}');

// RevenueCat In-App Purchases
despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');

// Contact Permissions
despia('requestcontactpermission://');
const contacts = await despia('readcontacts://', ['contacts']);

// Background Location
despia('backgroundlocationon://');
// Use native browser geolocation API (not despia native runtime)
const watchId = navigator.geolocation.watchPosition(
  (position) => console.log('Location:', position),
  (error) => console.error('Location error:', error)
);
// To stop
despia('backgroundlocationoff://');
navigator.geolocation.clearWatch(watchId);

// Push Notifications
despia('registerpush://');
despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
const oneSignalData = await despia('getonesignalplayerid://', ['onesignalplayerid']);

// Haptic Feedback
despia('lighthaptic://');
despia('heavyhaptic://');
despia('successhaptic://');
despia('warninghaptic://');
despia('errorhaptic://');

// App Information
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceInfo = await despia('get-uuid://', ['uuid']);

// Screenshots and Scanning
despia('takescreenshot://');
despia('scanningmode://auto');
despia('scanningmode://on');
despia('scanningmode://off');

// Store and Location
const storeData = await despia('getstorelocation://', ['storeLocation']);

// Image and File Operations
despia('savethisimage://?url=${image_url}');
despia('file://${file_url}');

// App Control
despia('reset://');
const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);

// UI Controls
despia('spinneron://');
despia('spinneroff://');
despia('hidebars://on');
despia('hidebars://off');

// Sharing
despia('shareapp://message?=${message}&url=${url}');

// Status Bar Styling
despia('statusbarcolor://{255, 255, 255}');
despia('statusbartextcolor://{black}');

// Biometric Authentication
despia('bioauth://');
```

### Response
#### Success Response (200)
Responses vary depending on the command. Some commands return data (e.g., `getappversion`, `readcontacts`), while others provide immediate feedback or perform actions without returning data (e.g., haptic feedback, UI controls).

#### Response Example
```json
// Example for getappversion
{
  "versionNumber": "1.0.0",
  "bundleNumber": "1"
}

// Example for readcontacts
{
  "contacts": [
    { "name": "John Doe", "phone": "123-456-7890" },
    { "name": "Jane Smith", "phone": "987-654-3210" }
  ]
}

// Example for haptic feedback (no response data)
// void
```
```

--------------------------------

### Biometric Authentication

Source: https://www.npmjs.com/package/despia-native/v/1.0_activeTab=code

Guides through setting up and implementing biometric authentication using Despia's callback functions and commands.

```APIDOC
## Biometric Authentication

### Description
This section details the process of setting up and utilizing biometric authentication within the Despia environment. It involves defining callback functions for success, failure, and unavailability scenarios, and then triggering the authentication process.

### Method
`despia('bioauth://')`

### Parameters
None for the main trigger command.

### Request Example
```javascript
// Step 1: Set up the biometric authentication SDK
if (!document.getElementById("bioauth-sdk")) {
    const script = document.createElement("script")
    script.id = "bioauth-sdk"
    script.type = "text/javascript"
    script.textContent = `
        function onBioAuthSuccess() {
            window.bioauthSuccess()
        }
        function onBioAuthFailure(errorCode, errorMessage) {
            window.bioauthFailure(errorCode, errorMessage)
        }
        function onBioAuthUnavailable() {
            window.bioauthUnavailable()
        }
    `
    document.head.appendChild(script)
}

// Step 2: Define your callback functions
window.bioauthSuccess = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication successful");
        // Handle successful authentication
    }
}

window.bioauthFailure = function(errorCode, errorMessage) {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication failed:", errorCode, errorMessage);
        // Handle authentication failure
    }
}

window.bioauthUnavailable = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication unavailable");
        // Handle when biometric auth is not available
    }
}

// Step 3: Trigger biometric authentication
despia('bioauth://');
```

### Response
Callbacks are handled via `window.bioauthSuccess`, `window.bioauthFailure`, and `window.bioauthUnavailable`.
```

--------------------------------

### Despia Command Examples: Location, Notifications, Haptics

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependencies

Illustrates Despia SDK usage for background location services, push notification registration, sending local push messages, and triggering various haptic feedback types (light, heavy, success, warning, error).

```typescript
// Background Location
despia('backgroundlocationon://');
// Use native browser geolocation API (not despia native runtime)
const watchId = navigator.geolocation.watchPosition(
  (position) => console.log('Location:', position),
  (error) => console.error('Location error:', error)
);
// To stop
despia('backgroundlocationoff://');
avigator.geolocation.clearWatch(watchId);

// Push Notifications
despia('registerpush://');
despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');

// Haptic Feedback
despia('lighthaptic://');
despia('heavyhaptic://');
despia('successhaptic://');
despia('warninghaptic://');
despia('errorhaptic://');
```

--------------------------------

### Despia Command Execution with Response Variables

Source: https://www.npmjs.com/package/despia-native/index_activeTab=readme

Demonstrates executing a Despia command that returns data, using the `await` keyword and specifying the expected variable names. The example shows how to retrieve and log application version and bundle numbers.

```typescript
import despia from 'despia-native';

// Execute command and watch for response variables (await needed)
const result = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
console.log(result); // { versionNumber: '1.0.0', bundleNumber: '123' }
```

--------------------------------

### TypeScript Integration Example

Source: https://www.npmjs.com/package/despia-native/v/1.0_activeTab=readme

Demonstrates how to use the Despia Native SDK with TypeScript for type-safe interactions.

```APIDOC
## TypeScript Support

### Description
Full TypeScript definitions are included with the Despia Native SDK for type-safe development.

### Usage Examples

```typescript
import despia from 'despia-native';

// Type-safe usage with Despia commands and watching variables
const result: { versionNumber: string; bundleNumber: string } = await despia(
  'getappversion://',
  ['versionNumber', 'bundleNumber']
);

// Direct property access with type inference
const deviceInfo: any = despia.deviceInfo; 
```
```

--------------------------------

### Despia Command Examples: App Info, Screenshots, UI Controls

Source: https://www.npmjs.com/package/despia-native/index_activeTab=readme

Demonstrates despia-native commands for retrieving application and device information, taking screenshots, controlling scanning mode, and managing UI elements like spinners and status bars.

```typescript
// App Information
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceInfo = await despia('get-uuid://', ['uuid']);

// Screenshots and Scanning
despia('takescreenshot://');
despia('scanningmode://auto');
despia('scanningmode://on');
despia('scanningmode://off');

// Store and Location
const storeData = await despia('getstorelocation://', ['storeLocation']);

// Image and File Operations
despia('savethisimage://?url=${image_url}');
despia('file://${file_url}');

// App Control
despia('reset://');
const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);

// UI Controls
despia('spinneron://');
despia('spinneroff://');
despia('hidebars://on');
despia('hidebars://off');
```

--------------------------------

### UI Control Commands (JavaScript)

Source: https://www.npmjs.com/package/despia-native/v/1.0

Provides examples for controlling UI elements such as loading spinners and status bars visibility using Despia commands.

```javascript
// UI controls
despia('spinneron://');      // Show loading
despia('spinneroff://');     // Hide loading
despia('hidebars://on');     // Hide status bar
despia('hidebars://off');
```

--------------------------------

### Despia Command Examples: UI Controls, Sharing, Status Bar

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependencies

Details Despia commands for managing UI elements like spinners and bars, initiating app sharing with messages and URLs, and customizing the status bar color and text.

```typescript
// UI Controls
despia('spinneron://');
despia('spinneroff://');
despia('hidebars://on');
despia('hidebars://off');

// Sharing
despia('shareapp://message?=${message}&url=${url}');

// Status Bar Styling
despia('statusbarcolor://{255, 255, 255}');
despia('statusbartextcolor://{black}');
```

--------------------------------

### Despia Native Widget and Service Calls

Source: https://www.npmjs.com/package/despia-native/v/1.0_activeTab=code

Examples of calling native widgets and services using the despia() function. This includes interactions with SVG widgets, RevenueCat purchases, contact permissions, background location, push notifications, haptic feedback, app information, screenshots, scanning modes, store location, image/file operations, app control, sharing, status bar styling, and biometric authentication.

```javascript
despia('widget://${svg}?refresh=${refresh_time}');
despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');
despia('requestcontactpermission://');
const contacts = await despia('readcontacts://', ['contacts']);
despia('backgroundlocationon://');
// Use native browser geolocation API (not despia native runtime)
const watchId = navigator.geolocation.watchPosition(
  (position) => console.log('Location:', position),
  (error) => console.error('Location error:', error)
);
// To stop
despia('backgroundlocationoff://');
avigator.geolocation.clearWatch(watchId);
despia('registerpush://');
despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
const oneSignalData = await despia('getonesignalplayerid://', ['onesignalplayerid']);
despia('lighthaptic://');
despia('heavyhaptic://');
despia('successhaptic://');
despia('warninghaptic://');
despia('errorhaptic://');
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceInfo = await despia('get-uuid://', ['uuid']);
despia('takescreenshot://');
despia('scanningmode://auto');
despia('scanningmode://on');
despia('scanningmode://off');
const storeData = await despia('getstorelocation://', ['storeLocation']);
despia('savethisimage://?url=${image_url}');
despia('file://${file_url}');
despia('reset://');
const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);
despia('spinneron://');
despia('spinneroff://');
despia('hidebars://on');
despia('hidebars://off');
despia('shareapp://message?=${message}&url=${url}');
despia('statusbarcolor://{255, 255, 255}');
despia('statusbartextcolor://{black}');
despia('bioauth://');
```

--------------------------------

### Despia Command Examples (TypeScript)

Source: https://www.npmjs.com/package/despia-native/index_activeTab=versions

Presents a wide array of Despia commands for various functionalities, including native widgets, in-app purchases, permissions, location services, push notifications, haptic feedback, app information, screenshots, scanning modes, file operations, app control, UI controls, sharing, status bar styling, and biometric authentication.

```typescript
// Native Widgets
despia('widget://${svg}?refresh=${refresh_time}');

// RevenueCat In-App Purchases
despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');

// Contact Permissions
despia('requestcontactpermission://');
const contacts = await despia('readcontacts://', ['contacts']);

// Background Location
despia('backgroundlocationon://');
// Use native browser geolocation API (not despia native runtime)
const watchId = navigator.geolocation.watchPosition(
  (position) => console.log('Location:', position),
  (error) => console.error('Location error:', error)
);
// To stop
despia('backgroundlocationoff://');
avigator.geolocation.clearWatch(watchId);

// Push Notifications
despia('registerpush://');
despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
const oneSignalData = await despia('getonesignalplayerid://', ['onesignalplayerid']);

// Haptic Feedback
despia('lighthaptic://');
despia('heavyhaptic://');
despia('successhaptic://');
despia('warninghaptic://');
despia('errorhaptic://');

// App Information
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
const deviceInfo = await despia('get-uuid://', ['uuid']);

// Screenshots and Scanning
despia('takescreenshot://');
despia('scanningmode://auto');
despia('scanningmode://on');
despia('scanningmode://off');

// Store and Location
const storeData = await despia('getstorelocation://', ['storeLocation']);

// Image and File Operations
despia('savethisimage://?url=${image_url}');
despia('file://${file_url}');

// App Control
despia('reset://');
const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);

// UI Controls
despia('spinneron://');
despia('spinneroff://');
despia('hidebars://on');
despia('hidebars://off');

// Sharing
despia('shareapp://message?=${message}&url=${url}');

// Status Bar Styling
despia('statusbarcolor://{255, 255, 255}');
despia('statusbartextcolor://{black}');

// Biometric Authentication
despia('bioauth://');
```

--------------------------------

### Avoiding Non-Existent Methods

Source: https://www.npmjs.com/package/despia-native/index_activeTab=dependencies

Shows examples of calling methods that do not exist on the despia object, cautioning against their use.

```javascript
// Don't use non-existent methods
// despia.ready();    // This method doesn't exist
// despia.init();     // This method doesn't exist
// despia.setup();    // This method doesn't exist
```

--------------------------------

### Using despia-native with Await for Data

Source: https://www.npmjs.com/package/despia-native/index

Illustrates how to use `await` with despia function calls for commands that return data, such as fetching app version information or contacts. This requires passing an array of expected response keys.

```javascript
const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
console.log(appInfo); // { versionNumber: '1.0.0', bundleNumber: '123' }
```

```javascript
const contacts = await despia('readcontacts://', ['contacts']);
console.log(contacts); // { contacts: [...] }
```

--------------------------------

### Biometric Authentication

Source: https://www.npmjs.com/package/despia-native/v/1.0_activeTab=dependencies

Guides through setting up and using biometric authentication by defining callback functions and triggering the authentication process.

```APIDOC
## Biometric Authentication

### Description
Handles biometric authentication by setting up success, failure, and unavailable callbacks, and then initiating the authentication process.

### Method
JavaScript function calls through the `despia` object.

### Endpoint
`bioauth://` (Trigger command)

### Parameters
None for the trigger command.

### Request Example
```javascript
// Step 1: Set up the biometric authentication SDK
if (!document.getElementById("bioauth-sdk")) {
    const script = document.createElement("script")
    script.id = "bioauth-sdk"
    script.type = "text/javascript"
    script.textContent = `
        function onBioAuthSuccess() {
            window.bioauthSuccess()
        }
        function onBioAuthFailure(errorCode, errorMessage) {
            window.bioauthFailure(errorCode, errorMessage)
        }
        function onBioAuthUnavailable() {
            window.bioauthUnavailable()
        }
    `
    document.head.appendChild(script)
}

// Step 2: Define your callback functions
window.bioauthSuccess = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication successful");
        // Handle successful authentication
    }
}

window.bioauthFailure = function(errorCode, errorMessage) {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication failed:", errorCode, errorMessage);
        // Handle authentication failure
    }
}

window.bioauthUnavailable = function() {
    if (navigator.userAgent.includes("despia")) {
        console.log("Biometric authentication unavailable");
        // Handle when biometric auth is not available
    }
}

// Step 3: Trigger biometric authentication
despia('bioauth://');
```

### Response
Callbacks are handled via `window.bioauthSuccess`, `window.bioauthFailure`, and `window.bioauthUnavailable`.
```

--------------------------------

### Basic Despia Command Execution (JavaScript)

Source: https://www.npmjs.com/package/despia-native/v/1.0

Demonstrates how to execute a basic Despia protocol command that requires no response, and how to execute a command that returns response variables using await.

```javascript
import despia from 'despia-native';

// Execute a Despia protocol command (no response needed)
despia('lighthaptic://');

// Execute command and watch for response variables (await needed)
const result = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
console.log(result); // { versionNumber: '1.0.0', bundleNumber: '123' }
```
Tokens:
Raw