@capawesome/capacitor-pixlive

Unofficial Capacitor plugin for PixLive SDK by Vidinoti.

Installation

npm install @capawesome/capacitor-pixlive
npx cap sync

Android

SDK Setup

Copy the vdarsdk-release.aar file into your app's android/app/libs/ directory.

iOS

Please note, that this plugin does not support SPM but only Cocoapods as iOS dependency manager.

SDK Setup

The PixLive iOS SDK (VDARSDK.xcframework) must be manually added by copying VDARSDK.xcframework into ios/App/Frameworks/ in your Capacitor project.

Configuration

Configure the plugin in your capacitor.config.ts:

const config: CapacitorConfig = {
  plugins: {
    Pixlive: {
      licenseKey: 'YOUR_LICENSE_KEY',
      apiUrl: 'https://ar.vidinoti.com/api/api.php', // optional
      sdkUrl: 'https://sdk.vidinoti.com', // optional
    },
  },
};

| Prop | Type | Description | Default | | ---------------- | ------------------- | -------------------------------- | ------------------------------------------ | | licenseKey | string | The PixLive Maker license key. | | | apiUrl | string | The PixLive Maker API endpoint. | https://ar.vidinoti.com/api/api.php | | sdkUrl | string | The PixLive SDK resource server. | https://sdk.vidinoti.com |

Usage

import { Pixlive } from '@capawesome/capacitor-pixlive';

const synchronize = async () => {
  await Pixlive.synchronize({ tags: [['my-tag']] });
};

const createARView = async () => {
  await Pixlive.createARView({ x: 0, y: 0, width: 300, height: 400 });
};

API

• initialize()
• checkPermissions()
• requestPermissions(...)
• synchronize(...)
• synchronizeWithToursAndContexts(...)
• updateTagMapping(...)
• enableContextsWithTags(...)
• getContexts()
• getContext(...)
• activateContext(...)
• stopContext()
• getNearbyGPSPoints(...)
• getGPSPointsInBoundingBox(...)
• getNearbyBeacons()
• startNearbyGPSDetection()
• stopNearbyGPSDetection()
• startGPSNotifications()
• stopGPSNotifications()
• setNotificationsSupport(...)
• setInterfaceLanguage(...)
• createARView(...)
• destroyARView()
• resizeARView(...)
• setARViewTouchEnabled(...)
• setARViewTouchHole(...)
• getVersion()
• addListener('codeRecognize', ...)
• addListener('enterContext', ...)
• addListener('exitContext', ...)
• addListener('presentAnnotations', ...)
• addListener('hideAnnotations', ...)
• addListener('eventFromContent', ...)
• addListener('syncProgress', ...)
• addListener('requireSync', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

initialize()

initialize() => Promise<void>

Initialize the PixLive SDK.

This must be called before any other method.

Only available on Android and iOS.

Since: 8.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check the status of permissions.

Returns: Promise<PermissionStatus>

Since: 8.0.0

requestPermissions(...)

requestPermissions(options?: PixlivePluginPermission | undefined) => Promise<PermissionStatus>

Request permissions.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | PixlivePluginPermission |

Returns: Promise<PermissionStatus>

Since: 8.0.0

synchronize(...)

synchronize(options: SynchronizeOptions) => Promise<void>

Sync content from PixLive Maker filtered by tags.

Only available on Android and iOS.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | SynchronizeOptions |

Since: 8.0.0

synchronizeWithToursAndContexts(...)

synchronizeWithToursAndContexts(options: SynchronizeWithToursAndContextsOptions) => Promise<void>

Sync content filtered by tags, tour IDs, and context IDs.

Only available on Android and iOS.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------------------------- | | options | SynchronizeWithToursAndContextsOptions |

Since: 8.0.0

updateTagMapping(...)

updateTagMapping(options: UpdateTagMappingOptions) => Promise<void>

Update tag-to-context mappings for language filtering.

Only available on Android and iOS.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | UpdateTagMappingOptions |

Since: 8.0.0

enableContextsWithTags(...)

enableContextsWithTags(options: EnableContextsWithTagsOptions) => Promise<void>

Enable only contexts matching specific tags.

Only available on Android and iOS.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | options | EnableContextsWithTagsOptions |

Since: 8.0.0

getContexts()

getContexts() => Promise<GetContextsResult>

Get all synchronized contexts.

Only available on Android and iOS.

Returns: Promise<GetContextsResult>

Since: 8.0.0

getContext(...)

getContext(options: GetContextOptions) => Promise<GetContextResult>

Get a single context by ID.

Only available on Android and iOS.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | GetContextOptions |

Returns: Promise<GetContextResult>

Since: 8.0.0

activateContext(...)

activateContext(options: ActivateContextOptions) => Promise<void>

Programmatically trigger/activate a context.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | ActivateContextOptions |

Since: 8.0.0

stopContext()

stopContext() => Promise<void>

Stop the currently playing/active context.

Only available on Android and iOS.

Since: 8.0.0

getNearbyGPSPoints(...)

getNearbyGPSPoints(options: GetNearbyGPSPointsOptions) => Promise<GetNearbyGPSPointsResult>

Get GPS points near a given location, sorted by distance.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | GetNearbyGPSPointsOptions |

Returns: Promise<GetNearbyGPSPointsResult>

Since: 8.0.0

getGPSPointsInBoundingBox(...)

getGPSPointsInBoundingBox(options: GetGPSPointsInBoundingBoxOptions) => Promise<GetGPSPointsInBoundingBoxResult>

Get all GPS points within a geographic bounding box.

Only available on Android and iOS.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------------- | | options | GetGPSPointsInBoundingBoxOptions |

Returns: Promise<GetGPSPointsInBoundingBoxResult>

Since: 8.0.0

getNearbyBeacons()

getNearbyBeacons() => Promise<GetNearbyBeaconsResult>

Get contexts associated with nearby detected beacons.

Only available on Android and iOS.

Returns: Promise<GetNearbyBeaconsResult>

Since: 8.0.0

startNearbyGPSDetection()

startNearbyGPSDetection() => Promise<void>

Start background GPS proximity detection.

Only available on Android and iOS.

Since: 8.0.0

stopNearbyGPSDetection()

stopNearbyGPSDetection() => Promise<void>

Stop background GPS proximity detection.

Only available on Android and iOS.

Since: 8.0.0

startGPSNotifications()

startGPSNotifications() => Promise<void>

Enable GPS-triggered local notifications.

Only available on Android and iOS.

Since: 8.0.0

stopGPSNotifications()

stopGPSNotifications() => Promise<void>

Disable GPS-triggered local notifications.

Only available on Android and iOS.

Since: 8.0.0

setNotificationsSupport(...)

setNotificationsSupport(options: SetNotificationsSupportOptions) => Promise<void>

Enable or disable notification support.

Only available on Android and iOS.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------- | | options | SetNotificationsSupportOptions |

Since: 8.0.0

setInterfaceLanguage(...)

setInterfaceLanguage(options: SetInterfaceLanguageOptions) => Promise<void>

Set the language for SDK UI elements.

Only available on Android and iOS.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | options | SetInterfaceLanguageOptions |

Since: 8.0.0

createARView(...)

createARView(options: CreateARViewOptions) => Promise<void>

Create the native AR camera view at specified screen coordinates.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | CreateARViewOptions |

Since: 8.0.0

destroyARView()

destroyARView() => Promise<void>

Destroy the AR camera view.

Only available on Android and iOS.

Since: 8.0.0

resizeARView(...)

resizeARView(options: ResizeARViewOptions) => Promise<void>

Resize the AR view.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | ResizeARViewOptions |

Since: 8.0.0

setARViewTouchEnabled(...)

setARViewTouchEnabled(options: SetARViewTouchEnabledOptions) => Promise<void>

Enable or disable touch event interception on the AR view.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------- | | options | SetARViewTouchEnabledOptions |

Since: 8.0.0

setARViewTouchHole(...)

setARViewTouchHole(options: SetARViewTouchHoleOptions) => Promise<void>

Define a rectangular region where touches pass through the AR view to the web layer.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | SetARViewTouchHoleOptions |

Since: 8.0.0

getVersion()

getVersion() => Promise<GetVersionResult>

Get the version of the sdk.

Returns: Promise<GetVersionResult>

Since: 8.0.0

addListener('codeRecognize', ...)

addListener(eventName: 'codeRecognize', listenerFunc: (event: CodeRecognizeEvent) => void) => Promise<PluginListenerHandle>

Called when a QR code or barcode is scanned by the AR camera.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------- | | eventName | 'codeRecognize' | | listenerFunc | (event: CodeRecognizeEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('enterContext', ...)

addListener(eventName: 'enterContext', listenerFunc: (event: EnterContextEvent) => void) => Promise<PluginListenerHandle>

Called when an AR context is detected/entered.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------- | | eventName | 'enterContext' | | listenerFunc | (event: EnterContextEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('exitContext', ...)

addListener(eventName: 'exitContext', listenerFunc: (event: ExitContextEvent) => void) => Promise<PluginListenerHandle>

Called when an AR context is lost/exited.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------- | | eventName | 'exitContext' | | listenerFunc | (event: ExitContextEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('presentAnnotations', ...)

addListener(eventName: 'presentAnnotations', listenerFunc: () => void) => Promise<PluginListenerHandle>

Called when AR content/annotations become visible on screen.

| Param | Type | | ------------------ | --------------------------------- | | eventName | 'presentAnnotations' | | listenerFunc | () => void |

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('hideAnnotations', ...)

addListener(eventName: 'hideAnnotations', listenerFunc: () => void) => Promise<PluginListenerHandle>

Called when AR content/annotations are hidden.

| Param | Type | | ------------------ | ------------------------------ | | eventName | 'hideAnnotations' | | listenerFunc | () => void |

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('eventFromContent', ...)

addListener(eventName: 'eventFromContent', listenerFunc: (event: EventFromContentEvent) => void) => Promise<PluginListenerHandle>

Called when AR content dispatches a custom event.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------- | | eventName | 'eventFromContent' | | listenerFunc | (event: EventFromContentEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('syncProgress', ...)

addListener(eventName: 'syncProgress', listenerFunc: (event: SyncProgressEvent) => void) => Promise<PluginListenerHandle>

Called during synchronization with progress updates.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------- | | eventName | 'syncProgress' | | listenerFunc | (event: SyncProgressEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('requireSync', ...)

addListener(eventName: 'requireSync', listenerFunc: (event: RequireSyncEvent) => void) => Promise<PluginListenerHandle>

Called when the SDK requires synchronization with specific tags.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------- | | eventName | 'requireSync' | | listenerFunc | (event: RequireSyncEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 8.0.0

Interfaces

PermissionStatus

| Prop | Type | Description | Since | | ---------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- | ----- | | bluetooth | PermissionState | Permission state of the Bluetooth permission. Only available on iOS. | 8.0.0 | | bluetoothConnect | PermissionState | Permission state of the Bluetooth Connect permission. Only available on Android. | 8.0.0 | | bluetoothScan | PermissionState | Permission state of the Bluetooth Scan permission. Only available on Android. | 8.0.0 | | camera | PermissionState | Permission state of the Camera permission. | 8.0.0 | | location | PermissionState | Permission state of the Location permission. Only available on Android and iOS. | 8.0.0 | | notifications | PermissionState | Permission state of the Notifications permission. | 8.0.0 |

PixlivePluginPermission

| Prop | Type | Description | Since | | ----------------- | ------------------------------------ | --------------------------- | ----- | | permissions | PixlivePermissionType[] | The permissions to request. | 8.0.0 |

SynchronizeOptions

| Prop | Type | Description | Since | | ---------- | ----------------------- | ------------------------------ | ----- | | tags | string[][] | The tags to filter content by. | 8.0.0 |

SynchronizeWithToursAndContextsOptions

| Prop | Type | Description | Since | | ---------------- | ----------------------- | ------------------------------ | ----- | | tags | string[][] | The tags to filter content by. | 8.0.0 | | tourIds | number[] | The tour IDs to sync. | 8.0.0 | | contextIds | string[] | The context IDs to sync. | 8.0.0 |

UpdateTagMappingOptions

| Prop | Type | Description | Since | | ---------- | --------------------- | ---------------- | ----- | | tags | string[] | The tags to map. | 8.0.0 |

EnableContextsWithTagsOptions

| Prop | Type | Description | Since | | ---------- | --------------------- | -------------------------------- | ----- | | tags | string[] | The tags to enable contexts for. | 8.0.0 |

GetContextsResult

| Prop | Type | Description | Since | | -------------- | ---------------------- | ---------------------------------- | ----- | | contexts | Context[] | The list of synchronized contexts. | 8.0.0 |

Context

| Prop | Type | Description | Since | | ------------------------- | --------------------------- | ------------------------------------- | ----- | | contextId | string | The unique identifier of the context. | 8.0.0 | | name | string | The name of the context. | 8.0.0 | | description | string | null | The description of the context. | 8.0.0 | | lastUpdate | string | The last update timestamp. | 8.0.0 | | imageThumbnailURL | string | null | The URL of the thumbnail image. | 8.0.0 | | imageHiResURL | string | null | The URL of the high-resolution image. | 8.0.0 | | notificationTitle | string | null | The notification title. | 8.0.0 | | notificationMessage | string | null | The notification message. | 8.0.0 | | tags | string[] | The tags associated with the context. | 8.0.0 |

GetContextResult

| Prop | Type | Description | Since | | ------------- | ------------------------------------------- | ------------ | ----- | | context | Context | The context. | 8.0.0 |

GetContextOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ---------------------------------- | ----- | | contextId | string | The ID of the context to retrieve. | 8.0.0 |

ActivateContextOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ---------------------------------- | ----- | | contextId | string | The ID of the context to activate. | 8.0.0 |

GetNearbyGPSPointsResult

| Prop | Type | Description | Since | | ------------ | ----------------------- | ----------------------------------------- | ----- | | points | GPSPoint[] | The nearby GPS points sorted by distance. | 8.0.0 |

GPSPoint

| Prop | Type | Description | Since | | --------------------------------- | --------------------------- | ------------------------------------------------- | ----- | | contextId | string | The ID of the associated context. | 8.0.0 | | category | string | The category of the GPS point. | 8.0.0 | | label | string | The label of the GPS point. | 8.0.0 | | latitude | number | The latitude of the GPS point. | 8.0.0 | | longitude | number | The longitude of the GPS point. | 8.0.0 | | detectionRadius | number | null | The detection radius in meters. | 8.0.0 | | distanceFromCurrentPosition | number | The distance from the current position in meters. | 8.0.0 |

GetNearbyGPSPointsOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ---------------------------------------- | ----- | | latitude | number | The latitude of the reference location. | 8.0.0 | | longitude | number | The longitude of the reference location. | 8.0.0 |

GetGPSPointsInBoundingBoxResult

| Prop | Type | Description | Since | | ------------ | ----------------------- | --------------------------------------- | ----- | | points | GPSPoint[] | The GPS points within the bounding box. | 8.0.0 |

GetGPSPointsInBoundingBoxOptions

| Prop | Type | Description | Since | | ------------------ | ------------------- | ------------------------------------------ | ----- | | minLatitude | number | The minimum latitude of the bounding box. | 8.0.0 | | minLongitude | number | The minimum longitude of the bounding box. | 8.0.0 | | maxLatitude | number | The maximum latitude of the bounding box. | 8.0.0 | | maxLongitude | number | The maximum longitude of the bounding box. | 8.0.0 |

GetNearbyBeaconsResult

| Prop | Type | Description | Since | | -------------- | ---------------------- | -------------------------------------------- | ----- | | contexts | Context[] | The contexts associated with nearby beacons. | 8.0.0 |

SetNotificationsSupportOptions

| Prop | Type | Description | Since | | ------------- | -------------------- | ------------------------------------------------ | ----- | | enabled | boolean | Whether notifications support should be enabled. | 8.0.0 |

SetInterfaceLanguageOptions

| Prop | Type | Description | Since | | -------------- | ------------------- | ------------------------- | ----- | | language | string | The language code to set. | 8.0.0 |

CreateARViewOptions

| Prop | Type | Description | Since | | ------------ | ------------------- | ------------------------------ | ----- | | x | number | The x position of the AR view. | 8.0.0 | | y | number | The y position of the AR view. | 8.0.0 | | width | number | The width of the AR view. | 8.0.0 | | height | number | The height of the AR view. | 8.0.0 |

ResizeARViewOptions

| Prop | Type | Description | Since | | ------------ | ------------------- | ---------------------------------- | ----- | | x | number | The new x position of the AR view. | 8.0.0 | | y | number | The new y position of the AR view. | 8.0.0 | | width | number | The new width of the AR view. | 8.0.0 | | height | number | The new height of the AR view. | 8.0.0 |

SetARViewTouchEnabledOptions

| Prop | Type | Description | Since | | ------------- | -------------------- | ---------------------------------------------------------- | ----- | | enabled | boolean | Whether touch events should be intercepted by the AR view. | 8.0.0 |

SetARViewTouchHoleOptions

| Prop | Type | Description | Since | | ------------ | ------------------- | ----------------------------------------------- | ----- | | top | number | The top coordinate of the touch hole region. | 8.0.0 | | bottom | number | The bottom coordinate of the touch hole region. | 8.0.0 | | left | number | The left coordinate of the touch hole region. | 8.0.0 | | right | number | The right coordinate of the touch hole region. | 8.0.0 |

GetVersionResult

| Prop | Type | Description | Since | | ------------- | ------------------- | ----------------------- | ----- | | version | string | The version of the sdk. | 8.0.0 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

CodeRecognizeEvent

| Prop | Type | Description | Since | | ---------- | ------------------- | ----------------------------- | ----- | | code | string | The scanned code value. | 8.0.0 | | type | string | The type of the scanned code. | 8.0.0 |

EnterContextEvent

| Prop | Type | Description | Since | | --------------- | ------------------- | ------------------------------ | ----- | | contextId | string | The ID of the entered context. | 8.0.0 |

ExitContextEvent

| Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------------- | ----- | | contextId | string | The ID of the exited context. | 8.0.0 |

EventFromContentEvent

| Prop | Type | Description | Since | | ------------ | ------------------- | ----------------------------------- | ----- | | name | string | The name of the custom event. | 8.0.0 | | params | string | The parameters of the custom event. | 8.0.0 |

SyncProgressEvent

| Prop | Type | Description | Since | | -------------- | ------------------- | -------------------------------------------- | ----- | | progress | number | The sync progress value between 0.0 and 1.0. | 8.0.0 |

RequireSyncEvent

| Prop | Type | Description | Since | | ---------- | --------------------- | -------------------------------------- | ----- | | tags | string[] | The tags that require synchronization. | 8.0.0 |

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

PixlivePermissionType

'bluetooth' | 'bluetoothConnect' | 'bluetoothScan' | 'camera' | 'location' | 'notifications'