Developers
Adsgun gives developers CSS hooks, storefront events and a small JavaScript API on window.AdsGun. Use them in your theme or in Adsgun’s Custom CSS and Custom JS to change how your store looks and behaves while a promotion runs.
For price markup, see Dynamic Pricing Schema and Schema Liquid Variables.
1 Page attributes
Adsgun sets these attributes while a promotion runs, and removes them when it ends.
| Attribute | Where | Value |
|---|---|---|
data-adsguncode |
<body> |
The codes in use, separated by commas, for example SUMMER10 or SUMMER10,FREESHIP. |
data-adsgunlink |
<body> |
The active promotion’s key: its title, the same value as in its private link ?adsgunlink=. |
data-adsgun-sale |
Each product card and product block Adsgun renders | "true" when the item is discounted, "false" when not. |
Several codes at once. The codes in data-adsguncode are separated by commas, not spaces, so [data-adsguncode~="CODE"] matches only while CODE is the only code in use. To match one code also when other codes are applied with it, use the four selectors in the One code example below.
Section 3 has ready CSS examples for these attributes.
2 Custom CSS and Custom JS
Go to Settings > Custom theme code in Adsgun, then open Custom CSS or Custom JS.
- The code is saved for your store, not per theme. It is used on every theme where the Adsgun app embed is on.
- Custom CSS is added in a
<style>tag, and Custom JS in a<script>tag, on every storefront page where the Adsgun app embed is on. - It runs for every visitor, with or without a promotion. To limit it to a promotion, use the examples in section 3.
- Custom JS runs early, before Adsgun has finished starting. Listen for Adsgun’s events with
window.addEventListener(section 4). - Do not include
<style>or<script>tags yourself. Adsgun adds them. - To remove the code, clear the editor and save.
Developer feature. Code added here runs on your live storefront for all visitors. A mistake can break how your store looks or works. Test on a theme preview first.
The Adsgun assistant can also propose a change to your Custom CSS or JS. It shows the new code on an approval card (“View code”). Nothing changes until you press I agree, do it, and Put it back restores the previous code.
For CSS that belongs to the price markup of one theme, prefer the schema’s css, hide and style_rules fields. They are saved per theme and only apply while prices are applied.
3 Code that runs only while a promotion is active
Each example says what it does, then shows the code. Copy it into Custom CSS or Custom JS and change the code names (SUMMER10, VIP5) and class names (.my-promo-banner) to your own. Class names of your theme’s elements differ from theme to theme: find them with your browser’s “Inspect” tool.
CSS examples
Every rule is scoped under a page attribute, so it applies only while the promotion or code is active and stops when it ends.
Any code
Shows your own banner only while any Adsgun code is applied. Hide it by default, then show it under body[data-adsguncode].
body[data-adsguncode] .my-promo-banner { display: block; }
One code
Only while the code SUMMER10 is applied, also when other codes are applied with it. The four selectors cover SUMMER10 alone, first, last and in the middle of the list.
body[data-adsguncode^=”SUMMER10,”] .my-promo-banner,
body[data-adsguncode$=”,SUMMER10″] .my-promo-banner,
body[data-adsguncode*=”,SUMMER10,”] .my-promo-banner {
display: block;
background: #ffe8e8;
}
A look per code
A different look for each code: green while SUMMER10 is applied, gold while VIP5 is applied.
body[data-adsguncode^=”SUMMER10,”] .my-promo-banner,
body[data-adsguncode$=”,SUMMER10″] .my-promo-banner,
body[data-adsguncode*=”,SUMMER10,”] .my-promo-banner { background: #e3f6e8; }
body[data-adsguncode=”VIP5″] .my-promo-banner,
body[data-adsguncode^=”VIP5,”] .my-promo-banner,
body[data-adsguncode$=”,VIP5″] .my-promo-banner,
body[data-adsguncode*=”,VIP5,”] .my-promo-banner { background: #fff4d6; }
One promotion
By the promotion instead of its codes: data-adsgunlink holds the active promotion’s key, the same value as in its private link.
Discounted products
Styles the product cards and product pages that Adsgun shows at a discounted price, and the ones that stay at full price. .price-item--sale is a class of the Dawn theme: use your theme’s price class.
color: #c4161c;
font-weight: 700;
}
[data-adsgun-sale=”false”] .my-sale-label { display: none; }
Theme sale badge
Hides the theme’s own “Sale” badge while an Adsgun code is applied, so shoppers don’t see two sale labels. .badge--sale is the Dawn theme’s class.
Site-wide bar
A fixed bar at the top of every page while the code BIGANNUAL is applied. The attribute is on <body>, so the bar is the body’s own ::before, and the padding keeps the page from sliding under it.
body[data-adsguncode^=”BIGANNUAL,”]::before,
body[data-adsguncode$=”,BIGANNUAL”]::before,
body[data-adsguncode*=”,BIGANNUAL,”]::before {
content: “Annual Big Sale – Extra 20% Off Everything!”;
display: block;
background-color: #c4161c;
color: #fff;
text-align: center;
padding: 10px;
position: fixed;
top: 0;
left: 0;
right: 0;
z-index: 1000;
}
body[data-adsguncode=”BIGANNUAL”],
body[data-adsguncode^=”BIGANNUAL,”],
body[data-adsguncode$=”,BIGANNUAL”],
body[data-adsguncode*=”,BIGANNUAL,”] {
padding-top: 40px;
}
JavaScript examples
A promotion can start when the page loads, when a code is applied without a reload, or when a scheduled promotion begins while the page is open. It can end on a schedule, at the end of a visitor’s session, or without a reload. Run your code when it starts and undo it when it ends.
Promotion starts
AdsGun::promotion:activated fires on every page where a promotion or discount code is active: on a normal visit, when a scheduled promotion starts while the page is open, and after AdsGun.activate(). It works on every plan.
var detail = event.detail || {};
// detail.promotionKey: the promotion
// detail.codes: the codes in use, for example [“SUMMER10”]
// detail.reason: “page_load”, “schedule” or “api”
document.documentElement.classList.add(‘promo-active’);
});
Promotion ends
Undo your change when the promotion ends without a page reload: its schedule ended, the visitor’s session ended, or another promotion replaced it.
document.documentElement.classList.remove(‘promo-active’);
});
One code
Runs only when the code SUMMER10 is among the codes in use. Here it changes the text of the theme’s announcement bar (.announcement-bar__message is the Dawn theme’s class).
var codes = (event.detail && event.detail.codes) || [];
if (codes.indexOf(‘SUMMER10’) === -1) return;
var bar = document.querySelector(‘.announcement-bar__message’);
if (bar) bar.textContent = ‘Summer sale: 10% off is applied at checkout’;
});
Check any time
For code that may run after the event has already fired, for example a script loaded late: read the data-adsguncode attribute on <body>.
var value = document.body ? document.body.getAttribute(‘data-adsguncode’) : ”;
return value ? value.split(‘,’) : [];
}
document.addEventListener(‘DOMContentLoaded’, function () {
if (adsgunCodes().indexOf(‘SUMMER10’) !== -1) {
// SUMMER10 is applied on this page
}
});
Follow every change
Starts and stops your code by itself, whenever codes are applied or removed, also without a reload. Set CODE to the code to react to, or to '' for any promotion.
var CODE = ‘BFCM’;
var running = false;
function isActive() {
var value = document.body.getAttribute(‘data-adsguncode’);
if (!value) return false;
return CODE === ” || value.split(‘,’).indexOf(CODE) !== -1;
}
function start() {
document.documentElement.classList.add(‘bfcm-live’);
// add your elements or listeners here
}
function stop() {
document.documentElement.classList.remove(‘bfcm-live’);
// remove everything start() added
}
function sync() {
var active = isActive();
if (active && !running) { running = true; start(); }
if (!active && running) { running = false; stop(); }
}
function boot() {
new MutationObserver(sync).observe(document.body, {
attributes: true,
attributeFilter: [‘data-adsguncode’, ‘data-adsgunlink’]
});
sync();
}
if (document.body) boot();
else document.addEventListener(‘DOMContentLoaded’, boot);
})();
After prices update
Adsgun places its prices after the page loads, and again for cards loaded later (AdsGun::item:price:applied also fires when the shopper picks another variant on the product page). It also rewrites the cart discounts after your theme drew the cart. Refresh your own theme parts after each.
// event.detail.roots: the product cards and pages that were just priced
});
window.addEventListener(‘AdsGun::discounts:recalculated’, function () {
// for example, ask your theme’s cart drawer to reload its contents
});
Always undo your changes on AdsGun::promotion:deactivated, or use the Follow every change pattern, which undoes them by itself.
4 Events
Every event is dispatched on window. You can also use AdsGun.events.listen(name, callback) once Adsgun has loaded. AdsGun.events.list lists every event with its description.
console.log(e.detail.roots);
});
Start-up
| Event | When | detail |
|---|---|---|
AdsGun::ready |
The script is loaded and window.AdsGun exists, before start-up. Paid plans only. |
{} |
AdsGun::init |
Start-up is finished: codes are checked and applied, prices are shown. Paid plans only. | {} |
// Adsgun is ready; discounts are applied and prices are shown
});
On every plan, AdsGun.initialized is true once start-up is finished.
Prices
| Event | When | detail |
|---|---|---|
AdsGun::prices:applied |
Prices were applied to a batch of cards or the product page. | { key, roots } |
AdsGun::item:price:applied |
One card or product block was rendered. Fires again on the product page when the shopper switches variant. | { item, root, key, hasDiscount, product, selectedVariant } |
AdsGun::lazy:loaded |
Cards that scrolled into view were rendered. | { key, roots } |
AdsGun::prices:reverted |
Prices were put back after the promotion ended. | {} |
Promotions and schedules
| Event | When | detail |
|---|---|---|
AdsGun::promotion:activated |
A promotion or discount code is active on the page: on a normal visit, when a scheduled promotion starts, and after AdsGun.activate(). Once per activation. |
{ promotionKey, codes, reason } |
AdsGun::promotion:deactivated |
A promotion was deactivated without a page reload. | {} |
AdsGun::schedule:set |
A promotion will start later while the page is open. | { promotionKey, startTimestamp, priority } |
AdsGun::schedule:activated |
That scheduled promotion has started. | { promotionKey, activePromotionKey } |
AdsGun::schedule:ended |
The active promotion’s schedule has ended. | { promotionKey } |
AdsGun::session:expired |
The visitor’s promotion session has ended. | { promotionKey } |
Cart
| Event | When | detail |
|---|---|---|
AdsGun::cart:update |
The cart was synced. | {} |
AdsGun::cart:item:changed |
An add, update or change request to the cart was handled. | { url } |
AdsGun::discounts:recalculated |
Adsgun recalculated the cart discounts on page load, because a promotion started or the currency changed. Your theme’s cart was drawn before that, so refresh your cart drawer or cart section here. | { reason } ("activation" or "currency_change") |
5 JavaScript functions
Available on every plan
| Function | What it does |
|---|---|
AdsGun.initialized |
true once start-up is finished. |
AdsGun.deactivate(preventReload, url) |
Removes the active promotion and codes. Reloads the page unless preventReload is true. With a url, goes to that page instead of reloading. Returns a Promise. |
AdsGun.events.listen(name, callback) |
Adds a listener. The callback gets the event’s detail. |
AdsGun.events.unlisten(name, callback) |
Removes a listener. |
AdsGun.events.list |
All events and their descriptions. |
AdsGun._publish(name) |
Announces a schema subscribe name, for example after your quick view opens. |
AdsGun.formatMoney(cents) |
Formats an amount with your shop’s money format. |
AdsGun.replaceTemplate(template, data) |
Renders a Liquid template string with your data, the same way schema templates are rendered. |
AdsGun.getProductData(url) |
Returns a Promise with the product’s data. The argument must contain /products/. |
AdsGun.computeItemDiscount(product, variant, quantity) |
Calculates the active promotion’s discount for one item. |
AdsGun._isPaidPlan() |
true on a paid plan. |
Paid plans only
| Function | What it does |
|---|---|
AdsGun.activate(codes) |
Applies one code, or several codes separated by commas ("CODE1,CODE2"). Returns a Promise. |
AdsGun.activatePromotion(key) |
Activates a promotion by its key. Returns a Promise. |
AdsGun.activate
try {
await AdsGun.activate(“SUMMERSALE”);
console.log(“Discount applied”);
} catch (error) {
console.error(“Could not apply the discount:”, error);
}
}
.then(function () { console.log(“Discounts applied”); })
.catch(function (error) { console.error(error); });
Several codes must be combinable with each other in Shopify.
AdsGun.deactivate
await AdsGun.deactivate();
// Removes the codes without a reload
await AdsGun.deactivate(true);
console.log(“Discounts removed without a reload”);
6 Good practice
- Listen with
window.addEventListener. It works even beforewindow.AdsGunexists. - Undo everything your code adds when the promotion ends.
- Prefer schema fields (
product,variant_id,watch,subscribe,hide,css) over Custom JS for price markup. They are per theme, need no timing code and go away with the schema. - Test on a theme preview or with a private promotion link before you change the live store.