# Embeds

# Introduction

Sublime Ads allows you to easily embed a category, of your choosing, to any website using a simple script. Just like putting on your socks in the morning.

Limits concerning embedding

Note that you need to create a category with linked ads. Individual ads cannot be embedded by themselves. If you'd like to do so, I suggest you use the API to get what you need for fine grained control... because sometimes that's just the thing you need.

Also note:

Work in progress!

Embeds are a work in progress and I'm happy to take feedback to make it better for you.

And... also... (yup, I can do this all day):

Need something custom?

If you need something custom, which you can't find here, or even just a little bit of change to the markup, just let me know.

API usage

Note that using the embeds counts towards your API usage. For details, go here.

# Getting started

Once you've set up a category, you'll see an option to "Embed this category". Here is an example category I set up for testing:

Embed button

Hover over the button and you'll see two simple steps, with clear instructions.

Embed dropdown

# Step 1: Copy the script

This one is easy, just copy and paste the embed script to your website. It should ideally be placed in the head tag... or you can add it to the end of the body tag.

The script tag looks like this, and you can use the below no problem (just copy and paste away):

<script src="https://embed.sublimeads.com/embed.js" defer></script>

Note that you should use the "defer" option as set above. If you don't want to use that, please add the script to the end of your body tag.

Served via CDN

The script is loaded over CDN and is incredibly fast. It is delivered zipped at ~9KB and once in the browser, and ready, comes to ~27KB unzipped. I think this is a win and won't slow down your visitor's experience.

# Step 2: Copy the HTML tag

Next up is to copy your HTML tag and place it where you need to on your site.

This is how it looks like:

<div data-sublime-embed="PUBLIC_CATEGORY_ID"></div>

The most important part here is the data attribute: data-sublime-embed="PUBLIC_CATEGORY_ID". As long as you have some HTML element with this data attribute, and your category public id, it will work. That means you can have it in a <span> or whatever you choose. The embed script will look for this on your page, so make sure it's there.

Note that the embed code differs per category. This way it knows what ads, from which category, to render. For example PUBLIC_CATEGORY_ID, as in the example above, needs to be replaced by the public id of the category you're wanting to use.

You can find the public id of your category on the corresponding category page, next to the embed button. However, it will already be pre-filled for you when you copy and paste the snippet on the category page itself. Less to fiddle around with.

Once placed on your page, it will show a random ad from the category. Neat!

There will be random ads!

The embed script will always bring back a random ad that's within the chosen category. For more fine grained control, you can always use the API.

Don't place any markup within the embed div!

Once the embed data is loaded, it will remove any HTML found within the embed container. So please be aware of that. If you want to place some markup around it, you're more than welcome to do so.

As default, the ad that is first returned will be used for the duration of the session. That means, it will save the data to session storage, which will persist for the duration the visitor has your webpage open. Once they close the window or close the tab to your page, they will receive a new random ad on the next visit... might be the same ad of course, cause random is random after all. Sublime Ads embed will never set any cookies and will not track individual users/visitors.

As an added bonus, the above saves on data calls to the API.

So to recap:

  1. An ad is randomly chosen and shown to you, or your visitor.
  2. The ad will remain the same for the duration of the visit. That both saves on data usage and also gives a better experience to your visitors when they see the same ad.
  3. Once they close your page/website fully, the data stored, called session storage, is removed - meaning a new random ad will be displayed on the next visit.
  4. No data about the user is ever collected. We know nothing, and you should know nothing too. (If they tap on an ad, of course the tap will be registered... but that's it. No more, no less.)
  5. There ought to be a point 5... but I can't think of anything to put here.

And that's it. You've made it, your first embed! ✌️

# Config options

In addition to the simple embed, you can pass in a few options. So, taking our example above, we have the following base markup:

<div data-sublime-embed="5c3sO4cNrK2Jlg"></div>

You can further customise how the ad markup is returned by using an extra data attribute.

# Layout options

As default, the embed markup will return the title and image in one div, with a secondary div for content. This makes it easy for a stacked view for either the title at the top, or bottom of the image (via your CSS).

# Title within content

Data Attribute: data-content-together

If you want to have the image to the side you may want to move the title to the content div.

For this, you can use the following markup:

<div data-sublime-embed="5c3sO4cNrK2Jlg" data-content-together></div>

Note the addition of data-content-together. This tells the script to remove the title from the image div and move it into the content div. As easy as that.

# Title above image

Data Attribute: data-title-first

If you don't use the data-content-together option, and you're having problems styling the title to show above the image (the title is displayed below the image as default), you can add the following attribute:

<div data-sublime-embed="5c3sO4cNrK2Jlg" data-title-first></div>

Here we're using the data-title-first attribute. Also quite easy and feel free to experiment.

# Nice URL option

Data Attribute: data-nice-url

You can disable the Sublime Ads "tap" urls and replace them with the real URL if so needed. This is very useful if you don't want to track taps and instead just let the other end do what it needs.

Use the data-nice-url data attribute in your embed code.

# No storage option

Data Attribute: data-no-store

As default, Sublime Ads embeds will always store a random ad in the browser session storage. That means on any other page visits to your page, in the current session only, you'll always see the same ad/embed.

If you don't want this behaviour, and also if you're debugging (useful to set this when testing), you can use the data-no-store data attribute.

Data attributes are saved for the session

When testing different data attributes note that you should use the "data-no-store" option so you can see your changes. If they don't seem to be working, clear your session storage.

# Examples

Nothing like a show and tell...

The embeds come back un-styled, so you will need to add your own CSS styling to suit your needs, ideas and design. So get creative.

Here are two, quite simple, examples of how they look on my own website (opens new window).

Embed Example 1 Embed Example 2

# Embed API

If you want a little bit more control, without using the full API, you can use the embed endpoint.

Endpoint: https://sublimeads.com/api/embed

Pass in your public id of your category as the token parameter:


If it's valid and you have an active subscription, or you are within your usage limits, your response will look like this:

  "message": "Here is your freshly brewed tea... I mean ad.",
  "ad": {
    "public_id": "IhWUDHrlMQPLzQ",
    "image_url": "https://assets.sublimeads.com/i8400v010pykfxrpmmvk65xufo5k",
    "alternative_image_url": "https://sublimeads.com/images/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBJZz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--0877acc1ed8ba789abac0cdd9d08aa022820ea6d/some-nice-image.jpg",
    "title": "Sublime Ads",
    "content": "\u003cdiv\u003eA privacy focused \u003cstrong\u003ead management\u003c/strong\u003e service for your apps, websites and others.\u003c/div\u003e",
    "plain_content": "A privacy focused ad management service for your apps, websites and others.",
    "redirect_to_url": "https://sublimeads.com",
    "url": "https://sublimeads.com/tap/IhWUDHrlMQPLzQ/8V17X0nQLpm3iQ",
    "is_paused": false

For more information on the ad object, you read more about it here.

Only one random ad is returned within the chose category.

Last updated: 1/30/2021, 10:21:35 PM