Skip to main content

Cloud Events

Introduction​

Zapp offers a way to integrate with 3rd party provider using the cloud Events protocol - https://cloudevents.io/. Using Cloud Events you can integrate your custom implementation of actions that your app users are making, without the need to write any client side code.

Once you implement cloud events and configured it in Zapp, any time a user action is triggered on the app, your cloud events server will be notified.

Note: To integrate your cloud events server in the app go to the relevant plugin configuration and set your server URL.

List of available cloud events​

note

If the event doesn't define an explicit response, please use the following:

{
  "specversion": "1.0",
  "type": "com.applicaster.event.received.v1",
  "source": "<SERVER_URL>",
  "subject": "Event  <EVENT_UUID> was successfully received",
  "id": "<NEW_EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>"
}

Video Started (com.applicaster.video.started.v1)​

Description: Triggered any time a user starts video playback.

Plugin: Continue Watching (Quick Brick)

Request Payload:

{
  "specversion": "1.0",
  "type": "com.applicaster.video.started.v1",
  "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
  "subject": "Watched video segment <TIME> progress:0 <VIDEO_ID>",
  "id": "<EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>",
  "datacontenttype": "applicastion/json",
  "data": {
    "userIdentifier": "<ACCESS_TOKEN>",
    "videoId": "<UNIQUE_VIDEO_ID>",
    "secondsFromStart": "0",
    "progress": 0,
    "status": "VIDEO_STARTED"
  }
}

data.userIdentifier​

A string that represents the user. It's best to make use of the user's access_token and not the actual user id, to be able to make sure the request is authorized.

data.videoId​

The unique video id. The video id is taken from the entry id set on the Pipes2 JSON Feed.

:::

Video Stopped (com.applicaster.video.stopped.v1)​

Description: Triggered any time a user stops a videos.

Plugin: Continue Watching (Quick Brick)

Request Payload:

{
      "specversion": "1.0",
      "type": "com.applicaster.video.stopped.v1",
      "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
      "subject": "Watched video segment <TIME> progress:<PROGRESS> <VIDEO_ID>",
      "id": "<EVENT_UUID>",
      "time": "<TIME_IN_RFC3339_FORMAT>",
      "datacontenttype": "applicastion/json",
      "data": {
        "userIdentifier": "<ACCESS_TOKEN>",
        "videoId": "<UNIQUE_VIDEO_ID>",
        "secondsFromStart": <SECONDS_FROM_START>,
        "progress": <NUMBER_BETWEEN_0_TO_1>,
        "status": "<EVENT_STATUS>"
      }
    }

data.userIdentifier​

A string that represents the user. It's best to make use of the user's access_token and not the actual user id, to be able to make sure the request is authorized.

data.videoId​

The unique video id. The video id is taken from the entry id set on the Pipes2 JSON Feed.

data.secondsFromStart​

Indicates the second the user triggered the event.

data.progress​

A number between 0 - 1 indicating the movie progress (where 0 indicates the beginning of the video and 1 indicates its end).

data.status​

Can be one of the following values:

  • COMPLETED: The video is considered as completed.
  • VIDEO_STOPPED: The video was stopped without reaching the end of the video
note

Items can be considered as completed without reaching progress=1. To find out more check entry.extensions.auto_resume_completion_threshold.

Video Progress (com.applicaster.video.progress.v1)​

Description: Triggered on player progress change (based on the interval parameter configured in the Continue Watching plugin).

Plugin: Continue Watching (Quick Brick)

Supported Version:

  • iOS, Android, Apple TV, Android TV, Fire TV, Samsung TV, LG TV: 6.1.6
  • Roku: SDK 0.1.0

Make sure to enable the Enable Heartbeat switch on the plugin configuration.

Request Payload:

{
      "specversion": "1.0",
      "type": "com.applicaster.video.progress.v1",
      "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
      "subject": "Watched video segment <TIME> progress:<PROGRESS> <VIDEO_ID>",
      "id": "<EVENT_UUID>",
      "time": "<TIME_IN_RFC3339_FORMAT>",
      "datacontenttype": "applicastion/json",
      "data": {
        "userIdentifier": "<ACCESS_TOKEN>",
        "videoId": "<UNIQUE_VIDEO_ID>",
        "secondsFromStart": <SECONDS_FROM_START>,
        "progress": <NUMBER_BETWEEN_0_TO_1>,
        "status": "WATCHING",
        "sessionStartAt": <NUMBER IN SECONDS>,
      }
    }

data.userIdentifier​

A string that represents the user. It's best to make use of the user's access_token and not the actual user id, to be able to make sure the request is authorized.

data.videoId​

The unique video id. The video id is taken from the entry id set on the Pipes2 JSON Feed.

data.secondsFromStart​

Indicates the second the user triggered the event.

data.progress​

A number between 0 - 1 indicating the movie progress (where 0 indicates the beginning of the video and 1 indicates its end).

data.sessionStartAt​

Indicates the number of seconds the current session started at. This will be bigger then 0 in case the user already watched this video in the past.

Video Paused (com.applicaster.video.paused.v1)​

Description: Triggered on player pause.

Plugin: Continue Watching (Quick Brick)

Supported Version:

  • iOS, Android, Apple TV, Android TV, Fire TV, Samsung TV, LG TV: 6.1.6
  • Roku: SDK 0.1.0

The event could be configured to send heartbeat during pause. To enable this, make sure to enable the Send Heartbeat On Pause switch on the plugin configuration.

Request Payload:

{
      "specversion": "1.0",
      "type": "com.applicaster.video.paused.v1",
      "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
      "subject": "Watched video segment <TIME> progress:<PROGRESS> <VIDEO_ID>",
      "id": "<EVENT_UUID>",
      "time": "<TIME_IN_RFC3339_FORMAT>",
      "datacontenttype": "applicastion/json",
      "data": {
        "userIdentifier": "<ACCESS_TOKEN>",
        "videoId": "<UNIQUE_VIDEO_ID>",
        "secondsFromStart": <SECONDS_FROM_START>,
        "progress": <NUMBER_BETWEEN_0_TO_1>,
        "status": "VIDEO_PAUSED",
        "sessionStartAt": <NUMBER IN SECONDS>,
      }
    }

data.userIdentifier​

A string that represents the user. It's best to make use of the user's access_token and not the actual user id, to be able to make sure the request is authorized.

data.videoId​

The unique video id. The video id is taken from the entry id set on the Pipes2 JSON Feed.

data.secondsFromStart​

Indicates the second the user triggered the event.

data.progress​

A number between 0 - 1 indicating the movie progress (where 0 indicates the beginning of the video and 1 indicates its end).

data.sessionStartAt​

Indicates the number of seconds the current session started at. This will be bigger then 0 in case the user already watched this video in the past.

Video Interval Completed (com.applicaster.video.interval.v1)​

Description: The event is triggered when a player finishes a predetermined segment. A segment is deemed completed when a user successfully views the specified duration (interval), regardless of ads, fast forward, rewind, or seek actions.

Plugin: Continue Watching (Quick Brick)

Supported Version:

  • iOS, Android, Apple TV, Android TV, Fire TV, Samsung TV, LG TV: 9.0.0
  • Roku: SDK 5.8.0

To enable this, make sure to enable the Enable Video Interval switch on the plugin configuration.

Request Payload:

{
  "specversion": "1.0",
  "type": "com.applicaster.video.interval.v1",
  "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
  "subject": "Watched video interval <INTERVAL_DURATION> of video <VIDEO_ID>",
  "id": "<EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>",
  "datacontenttype": "application/json",
  "data": {
    "userIdentifier": "<ACCESS_TOKEN>",
    "videoId": "<UNIQUE_VIDEO_ID>",
    "interval": <INTERVAL_DURATION>,
    "status": "INTERVAL_COMPLETED"
  }
}

data.userIdentifier​

A string that represents the user. It's best to make use of the user's access_token and not the actual user id, to be able to make sure the request is authorized.

data.videoId​

The unique video id. The video id is taken from the entry id set on the Pipes2 JSON Feed.

data.interval​

The interval of video watched in seconds.

data.status​

Indicates the status of the event. In this case, "INTERVAL_COMPLETED" signifies that the user has watched the defined interval.

info

Additional data could be added to the event data object. In order to do so, the origin feed entry (e.g. the entry for the current playable video) should include the required data in "extensions.continue-watching".

for example, for the origin entry:

{
  "id": "12345",
  "title": "Some Video",
  "extensions": {
    "continue-watching": {
      "key1": "some info1",
      "key2": "some info2"
    }
  }
}

The "pause" event payload will be (the additional data will be added to all type of events):

{
  "specversion": "1.0",
  "type": "com.applicaster.video.paused.v1",
  "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
  "subject": "Watched video segment <TIME> progress:<PROGRESS> <VIDEO_ID>",
  "id": "<EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>",
  "datacontenttype": "applicastion/json",
  "data": {
    "userIdentifier": "<ACCESS_TOKEN>",
    "videoId": "12345",
    "secondsFromStart": <SECONDS_FROM_START>,
    "progress": <NUMBER_BETWEEN_0_TO_1>,
    "status": "VIDEO_PAUSED",
    "sessionStartAt": <NUMBER IN SECONDS>,
    "key1": "some info1", // data added
    "key2": "some info2" // data added
  }
}

Add to favorites (com.applicaster.favorites.added.v1)​

Description: Triggered any time a user adds an item to her favorites list

Plugin: Favorites

Request Payload:

{
  "specversion": "1.0",
  "type": "com.applicaster.favorites.added.v1",
  "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
  "subject": "<ENTRY_ID> added to favorites",
  "id": "<EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>",
  "datacontenttype": "applicastion/json",
  "data": {
    "userIdentifier": "<ACCESS_TOKEN>",
    "entryId": "<UNIQUE_ENTRYs_ID>"
  }
}

data.userIdentifier​

A string that represents the user. It's best to make use of the user's access_token/id_token and not the actual user id, to be able to make sure the request is authorized.

data.entryId​

The unique entry id. The entry id is taken from the entry id set on the Pipes2 JSON Feed.

Remove from favorites (com.applicaster.favorites.removed.v1)​

Description:: Triggered any time a user remove an item from favorites

Plugin: Favorites

Request Payload:

{
  "specversion": "1.0",
  "type": "com.applicaster.favorites.removed.v1",
  "source": "<APP_URLSCHEME>://<BUNDLE_ID>/versions/<VERSION>",
  "subject": "<ENTRY_ID> wast removed from favorites",
  "id": "<EVENT_UUID>",
  "time": "<TIME_IN_RFC3339_FORMAT>",
  "datacontenttype": "applicastion/json",
  "data": {
    "userIdentifier": "<ACCESS_TOKEN>",
    "entryId": "<UNIQUE_ENTRYs_ID>"
  }
}

data.userIdentifier​

A string that represents the user. It's best to make use of the user's access_token/id_token and not the actual user id, to be able to make sure the request is authorized.

data.entryId​

The unique entry id. The entry id is taken from the entry id set on the Pipes2 JSON Feed.

Server implementations guidelines​

  • Server should return a 201 status on success.
  • According to the Cloud Event specs the time should be in rfc3339 format e.g. 2021-04-12T23:20:50.52Z. Please make sure you implement your server accordingly.