window.Crowny Shopify

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.

Requirements

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.

Methods
  • FNCrowny.open(view?)
  • FNCrowny.close()
  • FNCrowny.toggle()
  • FNCrowny.isOpen()
  • FNCrowny.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.

HTMLCustom Liquid block
<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
The screen to open on: '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
FNCrowny.open(view?)
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 friend

Close the widget

Closes the widget. Does nothing if it is already closed.

Parameters

None.

Returns

void
FNCrowny.close()
Crowny.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
FNCrowny.toggle()
<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

boolean
FNCrowny.isOpen()
if (!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
Called once the widget is ready, with the Crowny object as its only argument.

Returns

void
FNCrowny.ready(callback)
Crowny.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'Home
The widget's start screen with the shopper's points. Same as Crowny.open() with no argument.
'deals'Deals
The rewards a shopper can spend their points on.
'earn'Ways to earn
Every way to earn points in your programme.
'tiers'Tiers
Your VIP tiers and what each one unlocks.
'activity'Activity
The shopper's points history. Best for signed-in shoppers: anyone else sees an empty history.
'refer'Refer a friend
The shopper's referral link and their referrals. Only useful when referrals are switched on in your programme.
Views
  • homeHome
  • dealsDeals
  • earnWays to earn
  • tiersTiers
  • activityActivity
  • referRefer a friend

Examples

Copy these into your theme and adjust the labels.

A row of buttons, one per screen

Send shoppers straight to the part of the programme they care about.

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

HTMLdata-crowny-open
<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.

HTMLToggle button
<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.

Liquidmain-account.liquid
{% 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.

JSOpen on load
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.

JScrowny:ready
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.

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

JSConsole
Crowny.open('tiers');
Crowny.isOpen();   // true
Crowny.close();
Crowny.isOpen();   // false

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 onclick example on this page.
  • Scripts that run while the page loads (for example in <head> or straight after an element) run before window.Crowny exists. Calling Crowny.open() there throws Crowny 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.

JSReady event
document.addEventListener('crowny:ready', function (event) {
  event.detail.open('deals');
});
HTMLtheme.liquid, inside <head>
<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

One widget
Your buttons and the floating launcher control the same widget. Opening from your button and closing with the widget's own close button work together.
Works without the launcher
Crowny.open() opens the widget even on pages where the floating launcher button isn't shown.
Embedded join block
If a page uses the embedded Crowny join block instead of the floating widget, that block is always open. open, close and toggle do nothing there, and isOpen() returns true.
No active programme
If the store has no active Crowny programme, every method does nothing and the console shows one warning. Your click handlers never throw, and ready callbacks don't run.
Reward links win over ?widget-open=
If a URL carries both a reward (QR code) link and ?widget-open=, the widget opens on the reward. A later Crowny.open() call still switches to the screen you ask for.
The API drives the same panel as the launcher, so there is never a second widget on the page.

Troubleshooting

Crowny is not defined
The call ran before the widget loaded, or the widget isn't on the page. Check that the Crowny app embed is switched on in your theme, and see Load order.
"The loyalty widget is not active on this store"
This console warning means the widget loaded but found no active programme for this store. Check that your programme is live in the Crowny portal.
Opens on Home instead of the screen I asked for
The view name isn't on the list. Check the spelling and use lower case.
Nothing happens when I click my button
If the page uses the embedded join block instead of the floating widget, the buttons have no effect (see Behaviour notes). Otherwise check the browser console for errors from your own script.