Links
Comment on page

Generate animated HTML5 ads

How to generate animated HTML5 ads - Abyssale REST API
This feature is available from the Advanced plan.
Animated HTML5 ads can be created by sending data and customisation parameters to the POST /async/banner-builder/{template_id}/generate endpoint (with the image_file_type property equals to html5), which will respond synchronously with only a generation_request_id property.
Once the generation is completed, the result will then be posted to the callback_url (webhooks system).
HTML5 Asynchronous generation process
  • Supported template type: Animated
  • Generation response type: Asynchronous (Webhooks or Polling)

Generation Request (1st & 2nd step)

In addition to the supported image properties, an html5 property can be sent through the Abyssale REST API call to customise & announce related constraints to generate a valid HTML5 zip file. Here are the available options:
  • click_tag: A string that will be used to redirect the user to a specific URL when clicking on the visual. That should be either:
    • a single URL (for instance: https://www.abyssale.com)
    • or a URL prefixed by an ad network macro (for instance: [UNENCODED_CLICK_REDIRECT]https://developers.abyssale.com/)
  • page_title: The page title of the html5 document
  • ad_network: The ad network that will be used to dynamically compute the html5 file according to the related network constraints. As of now, the following constraints are taken into account: The html5 folder structure, the maximum file size & the gsap link (cdn or within the zip file). Here are the supported ad networks (spec):
    • default: No constraint
    • google-ads
    • google-marketing (ex: doubleclick)
    • adform
    • adroll
    • amazon-ads
    • iab
  • repeat: Sets the number of times that the HTML5 banner should repeat after its first iteration.
    • To repeat indefinitely, use -1.
    • Default value is 0 : The HTML5 banner will be played only once.
  • include_backup_image: By default, it is set to false. If include_backup_image is set to true, an image file named backup_image.jpeg ll'be included in the HTML5 zip file.
The background video is not supported on the html5 generation (if the template contains one, it will just be skipped).

Sample request

​Do not forget to replace {YOUR-API-KEY} and {templateId}
cURL
Javascript
Python
curl -X POST -H "x-api-key:{YOUR-API-KEY}" -H "Content-Type: application/json" \
-d '{
"callback_url": "https://webhook.mycompany.com/images",
"image_file_type": "html5",
"html5": {
"click_tag": "{MY_CLICK_TAG}",
"page_title": "{MY_PAGE_TITLE}",
"ad_network": "default",
"repeat": 0,
"include_backup_image": false
},
"template_format_names": ["facebook-feed", "instagram-post", "iab-medium"],
"elements": {
"primary_text": {
"payload": "New branding available.",
"color": "#FF0000"
}
}
}' \
https://api.abyssale.com/async/banner-builder/{template_id}/generate
const axios = require('axios');
const payload = {
"callback_url": "https://webhook.mycompany.com/images",
"image_file_type": "html5",
"html5": {
"click_tag": "{MY_CLICK_TAG}",
"page_title": "{MY_PAGE_TITLE}",
"ad_network": "default",
"repeat": 0,
"include_backup_image": false
},
"template_format_names": ["facebook-feed", "instagram-post", "iab-medium"],
"elements": {
"primary_text": {
"payload": "New branding available.",
"color": "#FF0000"
}
}
}
// Replace {id} by your template ID
axios.post("https://api.abyssale.com/async/banner-builder/{id}/generate", payload, {
headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000}
}).then(response => {
console.log(response.data)
}j
import json
import requests
image_generation_payload = {
"callback_url": "https://webhook.mycompany.com/images",
"image_file_type": "html5",
"html5": {
"click_tag": "{MY_CLICK_TAG}",
"page_title": "{MY_PAGE_TITLE}",
"ad_network": "default",
"repeat": 0,
"include_backup_image": false
},
"template_format_names": ["facebook-feed", "instagram-post", "iab-medium"],
"elements": {
"primary_text": {
"payload": "New branding available.",
"color": "#FF0000"
}
}
}
# Do not forget to replace {YOUR-API-KEY} and {template_id}
r = requests.post("https://api.abyssale.com/async/banner-builder/{template_id}/generate",
headers={"x-api-key": "YOUR-API-KEY", "Content-Type": "application/json"},
data=json.dumps(image_generation_payload),
timeout=30
)
r.json()
All formats of a template can be generated by removing the template_format_names property.

Sample response

{
"generation_request_id": "df75afa8-5a77-4e03-aeef-6d1b6dd0580a"
}

Generation response (3rd step)

The generation response can be obtained either by polling the API or by receiving the response directly to a callback_url that was announced during the generation request. Either way the payload of the response will look like the NEW_BANNER_BATCH event.
  • Each format will be returned as a ZIP file
  • The cdn_url property won't be returned
  • A JPEG backup image (corresponding to the last frame of the animation) will be returned in the fallback_image_url property (under the file property).

Response Example

{
"id": "df75afa8-5a77-4e03-aeef-6d1b6dd0580a",
"banners": [
{
"id": "3bbde867-9b8b-4b5a-b976-bff40ee34d8f",
"format": {
"id": "facebook-feed",
"width": 1200,
"height": 1090
},
"template": {
"id": "0ebd5717-9c1e-46dc-9ac9-6fee030bdb1a",
"name": "test animation remy",
"created_at": 1685093576,
"updated_at": 1693300429
},
"file": {
"type": "zip",
"url": "https://cdn.test.com/.../file.zip"
"filename": "file.zip"
"fallback_image_url": "https://cdn.test.com/.../backup.jpeg"
}
},
...
]
}