DashboardiOSAndroidA8 Media PlayerConsumer APIManagement API
Guides

Content Delivery

Suggest Edits

From the Consumer API perspective, content delivery is initiated upon the detection of a trigger from the end-user application (API client). Triggers are configured by admin users as part of the campaign management process, with the goal of delivering relevant contextual content to be consumed by end-users.

Delivery by UUID

Each trigger in our system is assigned a UUID (unique identifier) that can be used to request content from the back end server.

Retrieving the trigger UUID from the "slug"

As a way to reduce the complexity of QR codes, our platform generates a short-link that contains a "slug" (short unique string) that is associated to each of our QR code triggers. This value can then be used to retrieve the "trigger_uuid" that is part of the full URL, which then can be used to request a delivery of content. 

GET shortlink?sl={slug}

Requesting content by trigger UUID

The delivery of content is possible by making a request to the content/deliver API endpoint and passing the trigger UUID:

POST content/deliver?trigger_uuid={trigger_uuid}

If content is available for delivery, the backend responds with a JSON object that represents the content item.

Delivery by Trigger Type

📘

To "Catch" content

You may notice that we make use of the verb "catch" in several parts of our documentation. This is a word we use for marketing purposes to refer to the action of an API client detecting a trigger in its environment and subsequently requesting the delivery of offers related to such trigger.

For more information on each type of trigger available, please refer to
https://docs.actv8me.com/docs/triggers-2

The following sections summarize the "catch" API endpoints available for each trigger type:

QR Code Trigger

QR Codes are widely used in advertising since they require low implementation effort.

To request content from the ACTV8me backend servers upon the scanning of a QR code by the end-user, you may use the following endpoint:

POST qrcode/{id}/catch

Reference: https://docs.actv8me.com/reference/post_qrcode-id-catch

Hyperlink Triggers

If your campaigns require the sending of URLs via email, text, or another transfer medium to your end-users for them to click and open either a web or mobile app, you may use the Hyperlink trigger to deliver contextual offers.

Your application may call the following endpoint to achieve such a purpose:

POST hyperlink/{id}/catch

Reference:
https://docs.actv8me.com/reference/post_hyperlink-hyperlink-id-catch

Media Trigger

A Media trigger can be any audio/visual media content available for end-user consumption. A typical use case for this trigger is when you want to deliver contextual offers to your users at specific moments when they are watching content on your video streaming website.

Time marks

As a developer, you can retrieve a list of pre-configured time marks (specific points in the media timeline) for the media content.

To retrieve the time marks for a media trigger, you may call the following endpoint:

GET media/{identifier}/timemarks

Reference: https://docs.actv8me.com/reference/get_media-identifier-timemarks

📘

You may want to highlight these markers in the timeline to let the users know something special should happen when they reach such points.

Catch

For the delivery of content, you need to provide the "timemark_start_at" value (from the valid time marks you retrieved in the previous section) to the following endpoint:

POST /media/{identifier}/catch?timemark_start_at={seconds}

Reference: https://docs.actv8me.com/reference/post_media-identifier-catch

📘

"One Screen" Experience

At ACTV8me, our "One Screen Experience" solution empowers consumers with the ability to auto-save offers to their mobile wallet (IOS or Android) with one-click, directly from commercials for later use when it is most convenient for them. This method can be leveraged across any mobile web video player (pre-roll or mid-roll ad units) or any third-party mobile application, allowing advertisers to deliver a call-to-action across their ads. This experience uses Media triggers as the basis for the request for content delivery by the API client.

For a demonstration of how this works, please visit the following link:
https://onescreen.actv8technologies.com/#/player?key=57438b5163e3a2d2b9079a17a783628c812fea32&media=https://actv8me-public-assets-devpartners.s3.amazonaws.com/f/9/f9ab5870-acef-11ea-9993-bfe2fa947c8b/audio/1591997881.mp4&adId=2006121437&skip=0&ios=1&android=1&desktop=1&jwp=0&env=devpartners

For more detailed documentation on how this experience is created at the API level, please refer to the following documentation:

Audio Trigger

If your application makes use of the ACTV8me audio detection technology, you may request the delivery of content by using the decoded value ("external_id") provided by the ACTV8me SDK upon detection of an audio trigger via the listening services. Please refer to the SDK documentation for more information on how to implement the SDKs.

The following method should be called to request contextual content: 

POST /audio/{external_id}/catch

Reference: https://docs.actv8me.com/reference/post_audio-external-id-catch

Geofence Trigger

If you have been granted permission from the user to retrieve device location information via GPS, you may trigger the delivery of content based on the user's positioning.

Retrieve "nearby" geofences

First, you need to provide the latitude and longitude coordinates of the user's device in order for them to be able retrieve the geofences that are in proximity to their device. 

GET /geofence/nearby?latitude{latitude}&longitude={longitude}

Reference: https://docs.actv8me.com/reference/get_geofence-nearby

Catch Content

After retrieving the geofences nearby, you may trigger the request to get contextual content when the user interacts with the geofence (i.e. enters the geofence): 

POST /geofence/{external_id}/catch

Reference: https://docs.actv8me.com/reference/post_geofence-external-id-catch

Beacon Trigger

Bluetooth beacons can serve as triggers to request the delivery of content when a user is in close proximity to them. A typical use case is of a user walking through the snacks section of a grocery store, and getting an offer from a specific candy brand.

📘

Although you are free to choose any beacon vendor of your preference, we recommend using an Eddystone compatible product.

Once your application detects a beacon around the device, you may use the retrieved eddystone_instance_id to request the delivery of content using the following endpoint:

POST beacon/{eddystone_instance_id}/catch

Reference: https://docs.actv8me.com/reference/post_beacon-eddystone-instance-id-catch

User Content

You may retrieve content that has been successfully delivered to the user by using the following endpoint:

GET /user/{id}/content

Reference: https://docs.actv8me.com/v1.2/reference/audio#get_user-id-content

User Content with Content id

If you need to retrieve a specific content item for the user, you should use the following endpoint:

GET /user/{id}/content/{content_id}

Reference: https://docs.actv8me.com/reference/get_user-id-content-content-id

Device Content (Anonymous User)

When the delivery of content is requested without the user being authenticated (no "bearer" token sent through the headers), the content is "attached" to the device. This content is retrievable via the following endpoint:

GET /device/{uuid}/content

Reference: https://docs.actv8me.com/reference/get_device-uuid-content

📘

Native Wallet integration

If the native wallet feature has been enabled for the delivered content, a JWT (Google Pay) and PKPass (Apple Pay) can be retrieved for such content item from the ACTV8me backend.

Google Wallet:

Apple Wallet:

Updated over 1 year ago