Capacitor PixLive Plugin

Unofficial Capacitor plugin for PixLive SDK by Vidinoti.

Use Cases

The PixLive plugin is typically used to build augmented reality experiences with content managed in PixLive Maker, for example:

• Interactive print media: Bring magazines, flyers, or posters to life with AR content that appears when a context is recognized by the AR camera.
• Guided tours: Synchronize tours and contexts to guide visitors through museums, exhibitions, or cities.
• Location-based experiences: Trigger content or local notifications when the user approaches GPS points or beacons.
• QR code interactions: React to QR codes and barcodes scanned by the AR camera via the codeRecognize event.

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

The following examples show how to synchronize content from PixLive Maker and display the AR view.

Synchronize content from PixLive Maker

Sync AR content from PixLive Maker filtered by tags so that it is available on the device. Only available on Android and iOS:

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

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

Display the AR view

Create the native AR camera view at the specified screen coordinates. Only available on Android and iOS:

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

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: 0.0.1

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check the status of permissions.

Returns: Promise<PermissionStatus>

Since: 0.0.1

requestPermissions(...)

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

Request permissions.

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

Returns: Promise<PermissionStatus>

Since: 0.0.1

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: 0.0.1

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: 0.0.1

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: 0.0.1

enableContextsWithTags(...)

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

Enable only contexts matching specific tags.

Only available on Android and iOS.

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

Since: 0.0.1

getContexts()

getContexts() => Promise<GetContextsResult>

Get all synchronized contexts.

Only available on Android and iOS.

Returns: Promise<GetContextsResult>

Since: 0.0.1

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: 0.0.1

activateContext(...)

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

Programmatically trigger/activate a context.

Only available on Android and iOS.

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

Since: 0.0.1

stopContext()

stopContext() => Promise<void>

Stop the currently playing/active context.

Only available on Android and iOS.

Since: 0.0.1

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: 0.0.1

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: 0.0.1

getNearbyBeacons()

getNearbyBeacons() => Promise<GetNearbyBeaconsResult>

Get contexts associated with nearby detected beacons.

Only available on Android and iOS.

Returns: Promise<GetNearbyBeaconsResult>

Since: 0.0.1

startNearbyGPSDetection()

startNearbyGPSDetection() => Promise<void>

Start background GPS proximity detection.

Only available on Android and iOS.

Since: 0.0.1

stopNearbyGPSDetection()

stopNearbyGPSDetection() => Promise<void>

Stop background GPS proximity detection.

Only available on Android and iOS.

Since: 0.0.1

startGPSNotifications()

startGPSNotifications() => Promise<void>

Enable GPS-triggered local notifications.

Only available on Android and iOS.

Since: 0.0.1

stopGPSNotifications()

stopGPSNotifications() => Promise<void>

Disable GPS-triggered local notifications.

Only available on Android and iOS.

Since: 0.0.1

setNotificationsSupport(...)

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

Enable or disable notification support.

Only available on Android and iOS.

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

Since: 0.0.1

setInterfaceLanguage(...)

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

Set the language for SDK UI elements.

Only available on Android and iOS.

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

Since: 0.0.1

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: 0.0.1

destroyARView()

destroyARView() => Promise<void>

Destroy the AR camera view.

Only available on Android and iOS.

Since: 0.0.1

resizeARView(...)

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

Resize the AR view.

Only available on Android and iOS.

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

Since: 0.0.1

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: 0.0.1

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: 0.0.1

getVersion()

getVersion() => Promise<GetVersionResult>

Get the version of the sdk.

Returns: Promise<GetVersionResult>

Since: 0.0.1

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: 0.0.1

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: 0.0.1

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: 0.0.1

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: 0.0.1

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: 0.0.1

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: 0.0.1

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: 0.0.1

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: 0.0.1

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.0.1

Interfaces

PermissionStatus

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

PixlivePluginPermission

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

SynchronizeOptions

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

SynchronizeWithToursAndContextsOptions

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

UpdateTagMappingOptions

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

EnableContextsWithTagsOptions

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

GetContextsResult

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

Context

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

GetContextResult

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

GetContextOptions

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

ActivateContextOptions

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

GetNearbyGPSPointsResult

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

GPSPoint

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

GetNearbyGPSPointsOptions

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

GetGPSPointsInBoundingBoxResult

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

GetGPSPointsInBoundingBoxOptions

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

GetNearbyBeaconsResult

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

SetNotificationsSupportOptions

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

SetInterfaceLanguageOptions

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

CreateARViewOptions

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

ResizeARViewOptions

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

SetARViewTouchEnabledOptions

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

SetARViewTouchHoleOptions

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

GetVersionResult

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

PluginListenerHandle

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

CodeRecognizeEvent

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

EnterContextEvent

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

ExitContextEvent

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

EventFromContentEvent

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

SyncProgressEvent

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

RequireSyncEvent

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

Type Aliases

PermissionState

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

PixlivePermissionType

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

FAQ

Which method do I have to call first?

The initialize() method must be called before any other method of the plugin. It initializes the PixLive SDK using the license key from your Capacitor configuration file (see Configuration).

How do I set up the PixLive SDK in my project?

The PixLive SDK itself is not bundled with the plugin. On Android, copy the vdarsdk-release.aar file into your app's android/app/libs/ directory. On iOS, copy VDARSDK.xcframework into ios/App/Frameworks/ in your Capacitor project. See the Installation section for details.

Does this plugin support Swift Package Manager?

No, this plugin only supports CocoaPods as the iOS dependency manager. Swift Package Manager is not supported.

Does this plugin work on the Web?

No, the plugin methods are only available on Android and iOS since they rely on the native PixLive SDK.

Which permissions does the plugin handle?

The plugin can check and request the camera, location, notifications, and Bluetooth permissions via the checkPermissions() and requestPermissions(...) methods. The Bluetooth permission is exposed as bluetooth on iOS and as bluetoothConnect and bluetoothScan on Android.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• Barcode Scanning: Scan barcodes and QR codes with ML Kit.
• Bluetooth Low Energy: Communicate with Bluetooth Low Energy devices such as beacons.
• Geocoder: Handle geocoding and reverse geocoding.