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

   import OWiCConnect from "owic-app-service";

2. Initialize OWiCConnect in your application's main component. For example, in Vue.js:

   // In App.vue's mounted function
   mounted() {
     OWiCConnect.initialize();
   }

API Documentation

OWiCAppService provides the following methods for interacting with OWiC Connect:

initialize()

Initializes the two-way communication system between the Experience and OWiC Connect.

• Usage: OWiCConnect.initialize()

getTagInfo()

Retrieves detailed information about the scanned OWiC tag.

• Returns: A Promise resolving to an object containing tag details. Example response:

  {
    "id": "tag-unique-id",
    "created_time": "creation-timestamp",
    "last_edited_time": "last-edit-timestamp",
    "created_by": { "id": "creator-user-id" },
    "last_edited_by": { "id": "editor-user-id" },
    "permissions": {
      "public": { "read": true, "write": true },
      "anon": { "read": true, "write": false }
    },
    "app": {
      "appId": "associated-app-id",
      "appData": {
        /* Custom app data */
      }
    },
    "platform": "web | mobile",
    "tag_id": "tag-identifier"
  }

getPlatform()

Determines the platform on which the Experience is running.

• Returns: A string indicating the platform ('web' or 'mobile').

getVersion()

Determines the version of OWiC Connect which the Experience is running on.

• Returns: A string indicating the version number (eg: '1.0.0').

getData(key)

Fetches data associated with a specified key.

• Parameters:
  • key (String): The key of the data to retrieve.
• Returns: A Promise resolving to the requested data. Example response for key = "videoGift":

  {
    "video": {
      "filename": "video-file-name",
      "url": "video-url",
      "type": "video-type"
    },
    "montage": [
      {
        "type": "image-type",
        "displayMode": "display-mode",
        "url": "image-url",
        "filename": "image-file-name"
      }
    ]
  }

setData(key, data)

Stores data under a specified key.

• Parameters:
  • key (String): The key under which to store the data.
  • data (Any): The data to store.
• Returns: A Promise resolving to an acknowledgment object. Example response for key = "memories":

  {
    "id": "response-id",
    "data": {
      "memories": [
        {
          "url": "image-url",
          "type": "image-type",
          "filename": "image-file-name"
        }
      ]
    },
    "errors": []
  }

setOnDataChanged(callback)

Sets a callback function that will be called when the data changes.

• Usage: OWiCConnect.setOnDataChanged(callback)
• Parameters:
  • callback: A function that will be called when the data changes.

getUser(uid)

Gets user information from the OWiC Connect platform.

• Usage: OWiCConnect.getUser(uid)
• Returns: A Promise resolving to an object with user details. Example response:

  {
    "id": "response-id",
    "data": {
      "user-id": {
        "uid": "user-id",
        "email": "user-email",
        "displayName": "user-display-name",
        "photoURL": "user-photo-url"
      }
    },
    "errors": []
  }

uploadMedia(fileObj, update)

Uploads media and provides progress updates.

• Parameters:
  • fileObj (Array): An array of file objects.
  • update (Function): A function called with upload progress.
• Returns: A Promise resolving to an array of uploaded file details. Example response:

  [
    {
      "type": "file-type",
      "filename": "file-name",
      "url": "file-url"
    }
  ]

requestImageUploadURL(name, type)

Requests a URL for uploading an image.

• Usage: OWiCConnect.requestImageUploadURL(name, type)
• Parameters:
  • name (String): The name of the image file.
  • type (String): The MIME type of the image file.
• Returns: A Promise resolving to the upload URL. Example response:

  {
    "id": "e22e9e6b-c02b-42fd-c405-6c32af5fe600",
    "uploadURL": "https://upload.imagedelivery.net/FxUufywByo0m2v3xhKSiU8/e22e9e6b-c02b-42fd-c405-6c32af5fe600"
  }

requestVideoUploadURL(name, type, duration?)

Requests a URL for uploading a video with a specified duration.

• Usage: OWiCConnect.requestVideoUploadURL(name, type, duration)
• Parameters:
  • name (String): The name of the video file.
  • type (String): The MIME type of the video file.
  • duration (Number?): The duration of the video in seconds.
• Returns: A Promise resolving to the upload URL. Example response:

  {
    "scheduledDeletion": "2014-01-02T02:20:00Z",
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "uploadURL": "www.example.com/samplepath"
  }

requestVideoUploadTus(name, type, size)

Requests a TUS (resumable upload) URL for uploading a video.

• Usage: OWiCConnect.requestVideoUploadTus(name, type, size)
• Parameters:
  • name (String): The name of the video file.
  • type (String): The MIME type of the video file.
  • size (Number): The size of the video file in bytes.
• Returns: A Promise resolving to the TUS upload URL. Example response:

  {
    "scheduledDeletion": "2014-01-02T02:20:00Z",
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "uploadURL": "www.example.com/samplepath"
  }

retrieveVideoById(id)

Retrieves details of a video by its ID.

• Usage: OWiCConnect.retrieveVideoById(id)
• Parameters:
  • id (String): The unique identifier of the video.
• Returns: A Promise resolving to an object with video details. Example response:

  {
    "allowedOrigins": ["example.com"],
    "created": "2014-01-02T02:20:00Z",
    "creator": "creator-id_abcde12345",
    "duration": 0,
    "input": {
      "height": 0,
      "width": 0
    },
    "liveInput": "fc0a8dc887b16759bfd9ad922230a014",
    "maxDurationSeconds": 1,
    "meta": {
      "name": "video12345.mp4"
    },
    "modified": "2014-01-02T02:20:00Z",
    "playback": {
      "dash": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.mpd",
      "hls": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.m3u8"
    },
    "preview": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/watch",
    "readyToStream": true,
    "readyToStreamAt": "2014-01-02T02:20:00Z",
    "requireSignedURLs": true,
    "scheduledDeletion": "2014-01-02T02:20:00Z",
    "size": 4190963,
    "status": {
      "errorReasonCode": "ERR_NON_VIDEO",
      "errorReasonText": "The file was not recognized as a valid video file.",
      "pctComplete": "string",
      "state": "inprogress"
    },
    "thumbnail": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumbnail.jpg",
    "thumbnailTimestampPct": 0.529241,
    "uid": "ea95132c15732412d22c1476fa83f27a",
    "uploadExpiry": "2014-01-02T02:20:00Z",
    "uploaded": "2014-01-02T02:20:00Z",
    "watermark": {
      "created": "2014-01-02T02:20:00Z",
      "downloadedFrom": "https://company.com/logo.png",
      "height": 0,
      "name": "Marketing Videos",
      "opacity": 0.75,
      "padding": 0.1,
      "position": "center",
      "scale": 0.1,
      "size": 29472,
      "uid": "ea95132c15732412d22c1476fa83f27a",
      "width": 0
    }
  }

requestLogin(type, email?, password?)

Requests a login of a specific type from the OWiC Connect platform.

• Usage: OWiCConnect.requestLogin(type)
• Parameters:
  • type (OWiCLoginTypes): The type of login to request.
  • email (String?): User email (email login only)
  • password (String?): User password (email login only)

requestFullscreen(isFullscreen, backgroundColor)

Requests to enter or exit fullscreen mode on the OWiC Connect platform.

• Usage: OWiCConnect.requestFullscreen(isFullscreen, backgroundColor)
• Parameters:
  • isFullscreen: A boolean indicating whether to enter (true) or exit (false) fullscreen mode.
  • backgroundColor: The hex background color to use in fullscreen mode.

leaveApp(type)

Requests to leave the app on the OWiC Connect platform.

• Usage: OWiCConnect.leaveApp(type)
• Parameters:
  • type: The type of page to navigate to after leaving the app.

Examples

Here are some examples of how to use OWiCAppService:

Initializing Communication

// In a React component
componentDidMount() {
  OWiCConnect.initialize();
}

Fetching Tag Data

async function getTagData() {
  let tagData = await OWiCConnect.getTagInfo();
  console.log(tagData);
}

Contribution

Contributions to OWiCAppService are welcome! Please read our contribution guidelines for more information.

License

OWiCAppService is licensed under AGPLv3 License.