HTML5 Javascript Library
- 03 Oct 2023
- 6 Minutes to read
- DarkLight
HTML5 Javascript Library
- Updated on 03 Oct 2023
- 6 Minutes to read
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
AdGear HTML5 is a JavaScript library containing functions facilitating the development and integration of Samsung DSP’s tracking and expandability capabilities in rich media advertisements.
The library enables advertisers to develop a myriad of modern ad units and make the integration of common and custom tracking elements trivial.
They also facilitate the wide-scale deployment of rich media ad units across all Samsung and Samsung DSP third-party certified inventories.
ADGEAR.html5 - methods
Initialization
To use more advanced functionality in the API such as detailed click and event tracking, ad container expandability, and to access ad server creative variable data, you must wait for the creative to be initialized. This is accomplished by registering one or more callbacks via the ADGEAR.html5.onceInitialized(callback API method.
<script type="text/javascript"> ADGEAR.html5.onceInitialized(function() {
/* Do other stuff via ADGEAR.html5 API */ });
</script>
onceInitialized(callbackFunction)
| Arguments | Type | Default | Description |
|---|---|---|---|
| callbackFunction | function | n/a | Function that will be called once the ADGEAR API is initialized and ready to use. |
Register a callback function to be called automatically once the parent (ad loader) has completed the initialization of the creative. If initialization has already been completed when this is called, the callback will be called immediately.
Example
ADGEAR.html5.onceInitialized(function(e){ console.log("init"); });
Click Tracking
We usually suggest using our ADGEAR.html5.clickthrough function to handle the click on an element. However, you can use the ADGEAR.html5.getClickURL function if you want to get the URL and handle the clickThrough yourself.
Since the ad will be served in an iframe, you must have the target set to "_blank" on your click buttons and links, otherwise, the destination URL will be loaded within the iframe or might be blocked by a popup blocker.
example: <a href="#" target="_blank">
Once the AdGear JS file is loaded, it will create or override javascript variable named clicktag, clickTag, and clickTAG.
If you are using those variables to get the click destination, make sure the AdGear JS file is loaded after you've defined those variables, or don't define them at all and let the AdGear JS file do it for you.
Do NOT have window.open() inside the href attribute of an <a> element. This will cause issues in certain browsers.
getClickUrl(name \[opt\], destinationUrl \[opt\])
| Arguments | Type | Default | Description |
|---|---|---|---|
| name | string | clickTAG | (optional) Name of the click in Samsung DSP. |
| destURL (destinationUrl) | url | n/a | (optional) Override the destination URL. |
Returns the full tracking and redirection URL as a string, for an ad server tracked click with the specified name, optionally forcing the final redirection to the specified destUrl instead of the ad server provided default destination URL.
If destUrl is not provided or null, the ad server click tracker URL will redirect to its default configured destination URL.
If name is not provided (null) or does not exist, the default name values clickTag, clickTAG, and clicktag are considered automatically and returned if found.
If there is no clicktag URL provided by the ad server, null is returned.
Returns null if the creative has not been initialized.
Example
var clickTAG = ADGEAR.html5.getClickUrl("clickTAG");
clickThrough(name \[opt\], destinationUrl \[opt\])
| Arguments | Type | Default | Description |
|---|---|---|---|
| name | string | clickTAG | (optional) Name of the click in Samsung DSP. |
| destURL (destinationUrl) | url | n/a | (optional) Override the destination URL. |
Opens a new browser tab or window to the effective destination URL resolved by the ad server click tracker identified by name.
If destUrl is not provided or null, the ad server click tracker URL will redirect to its default configured destination URL.
If name is not provided (null) or does not exist, the default name values clickTag, clickTAG, and clicktag are considered automatically and redirected to if found. If at least clicktag is not found in the creative ad server configuration, the call to clickThrough does nothing.
Calling clickThrough() before the creative is initialized will default to redirecting through the generic click tracker clickTag, even if the specified click name does exist in the creative's ad server configuration.
Example
<a id="click_button"></a>
<script>
document.getElementById("click_button").addEventListener("click", function() { ADGEAR.html5.clickThrough("clickTAG"); }, false);
</script>
Ad Server Variables
Samsung DSP supports various types of variables, all of which are accessible to the HTML5 creative:
- Configuration Variables
- ad server configuration variables
- values configured by ad operations in the ad server
- Impression Variables
- impression tag query string key/values
- values added to ad server tag by trafficker, publisher, network, or vendor
In any case, if you are building HTML5 creative and want to leverage a variable value, you need to know the expected variable’s type and name. These should be established with your ad operations and planning teams.
Configuration Variables
getConfigVar(name)
| Arguments | Type | Default | Description |
|---|---|---|---|
| name | string | n/a | Name of the configuration variable in Samsung DSP. |
Returns a string with the value corresponding to the ad server configuration variable specified by name.
If name is not provided (null) or does not exist in the creative ad server configuration, null is returned.
Returns null if the creative has not been initialized.
You can see the list of supported impression variables here: Samsung DSP Ad Server Variables.
Example
var declared_url = ADGEAR.html5.getConfigVar("declared_url");
Impression Variable
getImpressionVar(name)
| Arguments | Type | Default | Description |
|---|---|---|---|
| name | string | n/a | Name of the impression variable in Samsung DSP. |
Returns a string with the value corresponding to the ad impression variable specified by name.
If name is not provided (null) or does not exist in the creative ad server configuration, null is returned.
Returns null if the creative has not been initialized.
You can see the list of supported impression variables here: Samsung DSP Ad Server Variables.
Example
var exchange_name = ADGEAR.html5.getImpressionVar("exchange_name");
Samsung DSP Ad Server Variables
| Var Name | Var Type | Value Type | Description |
|---|---|---|---|
| advertiser_name | configuration | string | The configured name of the Samsung DSP advertiser to which the creative is associated. |
| campaign_name | configuration | string | The configured name of the Samsung DSP campaign to which the creative is associated. |
| flight_name | configuration | string | The configured name of the Samsung DSP flight to which the creative is associated. |
| creative_name | configuration | string | The configured name of the creative in Samsung DSP. |
| declared_url | configuration | string | The site URL, as declared by the exchange seller (e.g. "https://example.com/site/"). |
| exchange_name | impression | string | The name of the exchange through which the ad impression delivered. |
| exchange_seller_name | impression | string | The name of the seller on the exchange (if available) through which the ad impression delivered. |
| buyer_price | impression | number (float) | The winning price, with all fees and surcharges (ad serving, data, DSP, etc.) included, expressed in the currency of the Samsung DSP buyer account through which the creative delivered. |
| buyer_media_price | impression | number (float) | The winning media price, net of any additional fees and surcharges (ad serving, data, DSP, etc.), expressed in the currency of the Samsung DSP buyer account through which the creative delivered. |
| udata | dynamic | object | The set of key/values associated with the user's browser, if any, that were previously set via the Samsung DSP User Data Passback tag. The Samsung DSP User Data Passback tag can be optionally piggybacked into a Samsung DSP segment tag and used to store key/value data from the advertiser's website. Stored data is associated to the user for a period of time (typically up to 30 days from the moment the tag is called) and is automatically provided to HTML5 creative via the udata dynamic variable. |
Examples (Output)
| Type | File | Demo | Note |
|---|---|---|---|
| Banner | Banner.zip | demo | Simple 300×250 banner ad with a click. |
| Video | Banner Video.zip | demo | Simple video banner with a click. |
| Filmstrip | Filmstrip.zip | demo | Simple 300×600 filmstrip ad with a click. |
| Banner loading an XML | Banner XML.zip | demo | Simple 300×250 banner ad that loads an XML file. |
| Banner with config variables | Banner Configuration Variables.zip | demo | Simple 300×250 banner ad that loads config variables from Samsung DSP. |
Was this article helpful?
