Generate animated HTML5 ads

How to generate animated HTML5 ads - Abyssale REST API

This feature is available from the Prime 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.

Videos are supported on the html5 generation but are not designed to be published to ad networks.

Sample request

​Do not forget to replace {YOUR-API-KEY} and {templateId}

cURL

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

Javascript

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

Python

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"
      }
    },
    ...
  ]
}