owic-app-service v1.12.23

OWiC App Service

Introduction

OWiCAppService is a JavaScript package designed to enable web app developers to integrate their applications seamlessly with OWiC Connect. OWiC Connect is a platform used for scanning OWiC tags and providing enhanced interactive experiences. By using OWiCAppService, developers can turn their web apps into Experiences for OWiC Connect, facilitating a two-way communication system between the Experience (running in an iframe or webview) and the OWiC Connect application.

Installation

To install the OWiCAppService package, run the following command in your project directory:

npm install owic-app-service

Usage

To use OWiCAppService in your project:

1. Import the necessary components:

   import {
     OWiCConnect,
     OWiCPageTypes,
     OWICPlatform,
     OWiCLoginTypes,
     OWiCPreviewTypes,
   } from "owic-app-service";

2. Initialize OWiCConnect in your application's main component:

   OWiCConnect.initialize();

Available Constants

The package provides several enumeration objects for use with various methods:

OWiCReturnTypes

• URL: "url"
• BASE64: "base-64"

OWiCLoginTypes

• GOOGLE: "google"
• FACEBOOK: "facebook"
• APPLE: "apple"
• PASSWORD: "password"

OWiCPageTypes

• TAG: "tag"
• USER: "user"
• CAMERA: "camera"

OWiCPreviewTypes

• MARKDOWN: "markdown"
• IMAGE: "image"
• LINK: "link"

OWiCMediaPicker

• IMAGE: "image"
• VIDEO: "video"
• MULTIPLEIMAGES: "multipleImages"
• MULTIPLEMEDIA: "multipleMedia"

OWICPlatform

• BROWSER: "web"
• APP: "mobile"

API Documentation

Core Methods

initialize(options = {})

Initializes the communication bridge with OWiC Connect.

• Sets up message event listeners
• Starts heartbeat monitoring
• Retrieves initial tag information

setOnDataChanged(callback)

Sets a callback function to be triggered when data changes are detected.

• Parameters:
  • callback: Function to be called when data changes

getPlatform()

Returns the current platform (web or mobile).

• Returns: OWICPlatform.BROWSER or OWICPlatform.APP

getVersion()

Returns the current app version.

• Returns: Version string (e.g., "1.0.0")

Data Management

getTagInfo()

Retrieves detailed information about the current tag.

• Returns: Promise resolving to tag details

{
  id: "tag-id",
  // ... other tag properties
}

setData(key, data)

Stores data for the given key.

• Parameters:
  • key: String identifier
  • data: Data to store
• Returns: Promise resolving to operation result

getData(key)

Retrieves data for the given key.

• Parameters:
  • key: String identifier
• Returns: Promise resolving to stored data

getUser(uid = "me")

Retrieves user information.

• Parameters:
  • uid: User ID (defaults to "me")
• Returns: Promise resolving to user data

Media Handling

uploadMedia(data, update)

Uploads media files with progress updates.

• Parameters:
  • data: Media data to upload
  • update: Progress callback function
• Returns: Promise resolving to upload result

requestImageUploadURL(name, type)

Requests a URL for image upload.

• Parameters:
  • name: File name
  • type: File MIME type
• Returns: Promise resolving to upload URL

requestVideoUploadURL(name, type, duration)

Requests a URL for video upload.

• Parameters:
  • name: File name
  • type: File MIME type
  • duration: Video duration in seconds
• Returns: Promise resolving to upload URL

requestVideoUploadTus(name, type, size)

Requests a TUS upload URL for resumable video uploads.

• Parameters:
  • name: File name
  • type: File MIME type
  • size: File size in bytes
• Returns: Promise resolving to TUS upload URL

retrieveCFVideoById(id)

Retrieves video details by ID.

• Parameters:
  • id: Cloudflare Video ID
• Returns: Promise resolving to video details

retrieveMuxVideoById(id)

Retrieves video details by ID.

• Parameters:
  • id: Mux Video ID
• Returns: Promise resolving to video details

openMediaPicker(type = OWiCMediaPicker.MULTIPLEMEDIA, update)

Opens the media picker interface.

• Parameters:
  • type: Type of media to pick
  • update: Progress callback function
• Returns: Promise resolving to selected media

User Interface Control

requestLogin(type, email = null, password = null)

Initiates a login request.

• Parameters:
  • type: Login type (OWiCLoginTypes)
  • email: Optional email for password login
  • password: Optional password for password login

requestFullscreen(isFullscreen = true, backgroundColor = null)

Controls fullscreen mode.

• Parameters:
  • isFullscreen: Boolean to enter/exit fullscreen
  • backgroundColor: Optional background color

leaveApp(type = OWiCPageTypes.TAG)

Exits the current experience.

• Parameters:
  • type: Destination page type

Error Handling

The service includes built-in error handling for all asynchronous operations. Errors are returned in the response object's errors array.

License

OWiCAppService is licensed under AGPLv3 License.