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].

.my-promo-banner { display: none; }
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,
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,
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.

body[data-adsgunlink=”SUMMERSALE”] .summer-only { display: block; }

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.

[data-adsgun-sale=”true”] .price-item–sale {
  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.

body[data-adsguncode] .badge–sale { display: none; }

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,
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.

window.addEventListener(‘AdsGun::promotion:activated’, function (event) {
  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.

window.addEventListener(‘AdsGun::promotion:deactivated’, function () {
  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).

window.addEventListener(‘AdsGun::promotion:activated’, function (event) {
  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>.

function adsgunCodes() {
  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.

(function () {
  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.

window.addEventListener(‘AdsGun::prices:applied’, function (event) {
  // 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.

window.addEventListener(‘AdsGun::prices:applied’, function (e) {
  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. {}
window.addEventListener(‘AdsGun::init’, function () {
  // 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.
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

async function applyDiscounts() {
  try {
    await AdsGun.activate(“SUMMERSALE”);
    console.log(“Discount applied”);
  } catch (error) {
    console.error(“Could not apply the discount:”, error);
  }
}
AdsGun.activate(“SUMMERSALE,BLACKFRIDAY”)
  .then(function () { console.log(“Discounts applied”); })
  .catch(function (error) { console.error(error); });

Several codes must be combinable with each other in Shopify.

AdsGun.deactivate

// Removes the codes and reloads the page
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 before window.AdsGun exists.
  • 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.