Storefront widget JavaScript API
Open and close the Crowny loyalty widget from your own buttons,
menus and scripts with the global window.Crowny
object.
The widget normally opens from its floating launcher button.
With window.Crowny you can also put a "Rewards"
link in your header, footer, account page or anywhere else in
your theme, and open the widget straight on the screen you
want, such as Deals or Tiers.
The Crowny app embed is switched on in your Shopify theme (Online Store → Themes → Customize → App embeds).
Your store has an active Crowny loyalty programme.
Nothing to install: window.Crowny comes with
the widget.
- FN
Crowny.open(view?) - FN
Crowny.close() - FN
Crowny.toggle() - FN
Crowny.isOpen() - FN
Crowny.ready(callback)
Quick start
Add a button anywhere in your theme, for example in a Custom Liquid section or block.
Clicking it opens the widget on the Deals screen. Leave the
argument out (Crowny.open()) to open it on Home.
<button type="button" onclick="Crowny.open('deals')">Rewards</button>Open the widget
Opens the widget. With a view name, it opens on that screen.
When that screen isn't Home, the back arrow inside the widget
takes the shopper to Home. Calling open while the
widget is already open switches it to the requested screen.
Parameters
view
string
optional
'home',
'deals', 'earn',
'tiers', 'activity' or
'refer'. See
Views you can open. Leaving it out, or
passing a name that isn't on the list, opens Home.
Returns
void
Crowny.open(); // Home
Crowny.open('deals'); // Deals
Crowny.open('earn'); // Ways to earn
Crowny.open('tiers'); // Tiers
Crowny.open('activity'); // Activity
Crowny.open('refer'); // Refer a friendClose the widget
Closes the widget. Does nothing if it is already closed.
Parameters
None.
Returns
voidCrowny.close();Toggle the widget
Opens the widget if it is closed, closes it if it is open. When it opens, it shows the screen the shopper last had open.
Parameters
None.
Returns
void<button type="button" onclick="Crowny.toggle()">Rewards</button>Check whether the widget is open
Returns true when the widget is open and
false when it is closed.
Parameters
None.
Returns
booleanif (!Crowny.isOpen()) {
Crowny.open('earn');
}Run code once the widget is ready
Runs callback(Crowny) as soon as the widget is
ready, or straight away if it already is. Use it for code that
runs while the page is still loading. See
Load order.
Parameters
callback
(crowny) => void
required
Crowny object as its only argument.
Returns
voidCrowny.ready(function (crowny) {
console.log('Crowny widget is ready, open:', crowny.isOpen());
});Views you can open
These are the values you can pass to
Crowny.open(). They are the same names that
?widget-open= links use.
Names are case-sensitive: use lower case exactly as shown. Any
other value opens Home.
'home'HomeCrowny.open() with no argument.'deals'Deals'earn'Ways to earn'tiers'Tiers'activity'Activity'refer'Refer a friendhomeHomedealsDealsearnWays to earntiersTiersactivityActivityreferRefer a friend
Examples
Copy these into your theme and adjust the labels.
A "Rewards" link in your header or footer
Works on any element. Return false so the link
doesn't also jump to the top of the page.
<a href="#" onclick="Crowny.open(); return false;">Rewards</a>A row of buttons, one per screen
Send shoppers straight to the part of the programme they care about.
<div class="rewards-shortcuts">
<button type="button" onclick="Crowny.open('deals')">Spend points</button>
<button type="button" onclick="Crowny.open('earn')">Earn points</button>
<button type="button" onclick="Crowny.open('tiers')">VIP tiers</button>
<button type="button" onclick="Crowny.open('refer')">Refer a friend</button>
</div>Without inline onclick
Put the view name in a data- attribute and attach
one listener. Useful when your theme or Content Security Policy
doesn't allow inline handlers.
<a href="#" data-crowny-open="deals">Deals</a>
<a href="#" data-crowny-open="tiers">Tiers</a>
<script>
document.addEventListener('click', function (event) {
var link = event.target.closest('[data-crowny-open]');
if (!link || !window.Crowny) return;
event.preventDefault();
window.Crowny.open(link.getAttribute('data-crowny-open'));
});
</script>A toggle button whose label follows the widget
The label only updates on your own button's clicks: if the shopper closes the widget with its own close button, the label won't know.
<button type="button" id="rewards-toggle">Show rewards</button>
<script>
document.getElementById('rewards-toggle').addEventListener('click', function () {
Crowny.toggle();
this.textContent = Crowny.isOpen() ? 'Hide rewards' : 'Show rewards';
});
</script>A link in the customer account page
Show different copy to signed-in customers, for example in
main-account.liquid or a Custom Liquid
block.
{% if customer %}
<a href="#" onclick="Crowny.open('activity'); return false;">
See your points history
</a>
{% else %}
<a href="#" onclick="Crowny.open(); return false;">
Join our rewards programme
</a>
{% endif %}Open the widget when the page has loaded
Crowny.ready waits for the widget, so this works
even from a script high up in the page. It needs the
stub if it runs before the widget has
loaded.
Crowny.ready(function (crowny) {
crowny.open('earn');
});Listen for the ready event
Works without a stub. The event fires on document
and carries the Crowny object as
detail.
document.addEventListener('crowny:ready', function (event) {
var crowny = event.detail;
console.log('Widget ready, open:', crowny.isOpen());
});Check that the widget is there before calling it
On a page or store where the widget isn't loaded at all,
window.Crowny is undefined. Guard
calls from shared theme code.
if (window.Crowny) {
window.Crowny.open('deals');
}Try it from the browser console
Open your storefront, open the browser's developer console and run these lines.
Crowny.open('tiers');
Crowny.isOpen(); // true
Crowny.close();
Crowny.isOpen(); // falseOpening with a link instead
You don't always need JavaScript. Add
?widget-open= with a
view name to any link to your store, and
the widget opens on that screen when the page loads. This works
in Shopify navigation menus, emails, social posts and ads.
To add one to a Shopify menu, go to Online Store →
Navigation, add a menu item and use a link such as
/?widget-open=tiers.
These links also work when your theme changes the URL without a
full page load (for example themes with client-side navigation
or quick views). Only a link that changes opens the widget:
going back to a page without ?widget-open= doesn't
reopen it, and an unknown name does nothing.
https://your-store.com/?widget-open=deals
https://your-store.com/collections/all?widget-open=earn// Also opens the Earn screen, without a reload
history.pushState(null, '', '/?widget-open=earn');Load order
The widget loads after your page has been parsed. That means:
-
Click handlers just work. By the time a
shopper clicks, the widget has loaded. This covers every
onclickexample on this page. -
Scripts that run while the page loads (for
example in
<head>or straight after an element) run beforewindow.Crownyexists. CallingCrowny.open()there throwsCrowny is not defined.
For the second case, either listen for the
crowny:ready event, or paste the stub as high up
in theme.liquid as you can, inside
<head>. The stub records calls made before
the widget loads. When the widget loads, it replays them in
order, replaces the stub with the real Crowny
object and fires crowny:ready.
With the stub in place, Crowny.open() and
Crowny.ready() are safe to call from anywhere.
isOpen() answers false until the
widget has loaded.
document.addEventListener('crowny:ready', function (event) {
event.detail.open('deals');
});<script>
window.Crowny = window.Crowny || {
q: [],
open: function () { this.q.push(['open'].concat([].slice.call(arguments))); },
close: function () { this.q.push(['close']); },
toggle: function () { this.q.push(['toggle']); },
isOpen: function () { return false; },
ready: function (fn) { this.q.push(['ready', fn]); }
};
</script>Behaviour notes
Crowny.open() opens the widget even on pages where the floating launcher button isn't shown.open, close and toggle do nothing there, and isOpen() returns true.ready callbacks don't run.?widget-open=?widget-open=, the widget opens on the reward. A later Crowny.open() call still switches to the screen you ask for.Troubleshooting
Crowny is not defined