Because the ads are served through a url, they are the meat of the documentation. We will go through every part here in detail. All the parts have an order, an short identifier, and a long identifier, and any of them can be used in any order, except for the hardcoded order of the parts.
If you have an account, you can secure yourself an unique username. This username you can use as an identifier for your account. This comes in handy if you post your link on a guest blog, youtube, comment in a forum, etc. Because the origin is not owned by you, it is important that the username is added to the url.
Username is validated by being a combination of one or more lowercase words separated by a hyphen. In regex terms [\w-]+
This is how the user part can be in the url:
/between-movies/
/u:between-movies/
/user:between-movies/
After user in the hierarchy, comes company, or the affiliate provider. I use fiverr as an example, but it could be amazon or hostinger to name two others. To find out what you want to use, you have to log in to the system and see what is available.
/fiverr/
/c:fiverr/
/company:fiverr/
In case you want to show ads from a pool of multiple companies, you can separate them with a comma. This works best for 1-5 companies, so that the url does not get too long.
/c:fiverr,hostinger,audible,grammarly/
When you want a bigger pool, you can use the keyword in the same way instead, as described below.
/pro/
/p:pro/
/product:pro/
Since product is almost always tied to a company, for instance the pro plan of fiverr, you can combine them as such:
/fiverr:pro/
We would recommend you never use product by itself, unless it is a product that is sold in many places and who the affiliate provider is seems irrelevant. For instance ps-5 or geforce-4090.
Instead of using the company and product narrowing, you can narrow down by keywords that the ad will be selected by. The keywords can be multi word slugs with hyphens. The order of the keywords matter as well as the first ones are considered more important than the latter. Even if the keywords does not exists, they are added to the system so that they kan be implemented and expanded into.
/shoes/
/k:shoes/
/keyword:shoes/
/k:shoes,shirts,hats,clothes,green-color/
Type has a selected amount of options to choose from and it defines what is returned from the service. If not provided, the system will automatically try to determine the type. This is an option if you need to explicitly define the source, which may well be the case sometimes.
/image/
/t:image/
/type:image/
Currently the following are supported
script: src in a script tag. This is the default when none other is provided.
image: src in an img tag.
link: href in a tag that is wrapping a img tag.
html: Only for server side loading of the html. For instance in php you can write php file_get_contents('https://betweenaffiliates.com/t:html/c:fiverr/w:600/h:200/');
iframe: src of the iframe element.
url: href of the a tag.
Width and height are pretty straightforward, but there are a few variations to take note of. For instance, when using just the number width always comes first, meaning that you usually need to specify that you have selected the height if you can work with any width. You do not have to have a width or height, like if you use the url type, but if you want an image it will be random size. OTher than that you can use width only, or height only. If only width is specified, the ad you get wil have that width and a random height and visa versa.
/600/200/
/w:600/h:200/
/width:600/height:200/
There is also one special case, that you can use the following if you want:
/600x200/
You can also limit the width and height if you accept a random ad within a range. Note that in the example under you can be served a ad that is 400x300 or one that is 800x100.
/w:400-800/h:100-300/
Just a sidenote here as well, that if the width it 600x200 we will chose and ad from the range of 599-601 in order to get those that are one pixel away. This goes for height as well.
As an extra, instead of width x height, you can provide the ratio. For instance 16:9, 3:2, 1:1, etc. In this scenario, you may get a bigger or smaller ad that is resized so it may not be the best option by itself, but together with either width or height it may be an alternative.
/16/9/
/r:16x9/
/ratio:16x9/
Lastly, the version is to add caching and even control over caching. It is again not needed when an url type to one affiliate but it can be a good idea to add it in many cases, unless you want the same ad to be shown all the time. The number you put in will give you the cached version for that number, so for instance, if you put in a random number from 1-10, you will choose from a random pool of 10 ads. If you add a the current date like 20240504, it wil cache that ad for the same day, or if you add the hour of the day the ad will change every hour. We recommend you to have some caching going at it is for your benefit, and we may need to take action if you for instance use timestamp that will cache every second. If the version is not added, we will give you a random ad from a pool of 100.
/10/
/v:10/
/version:10/
If /10/ is used and there is no width or height specified, it will not work as width or height will be assumed.
What is extremely important is that if you wrap the image type with a link type, that the two stay otherwise identical, including the version - so that they can be grouped together.
The cached version will stay in cache for 24 hours.
In order to make the building of the url as flexible as possible, we also provide a shorthand that will strictly abide to the order they are in the docs here. You can thus write the whole url as this:
/between-movies:amazon:adidas:white,black:script:600:200:10/
It is however not recommended as it can be difficult to see what is for what, and thus guarantee that it will work as intended.
You can also log in to the system and define your own links, by giving the ad a personal slug making it work like you defined. So, if you did the work, the above can be written like this:
/between-movies/adidas-shoes/