Custom Events with Shopify

If you wish to record Custom Events into Katalys, and your integration uses the Katalys Shopify plugin (“public app” or “custom app” approach), you can use the Shopify API to forward these events directly into Katalys.

Custom events can be any string value that helps you analyze your traffic, except for a blacklist. See Reporting Custom Events for examples.

Quickstart

Sending an event to Katalys via the Shopify JavaScript API is very simple. Here is a script template:

HTML

<script>
  let eventName = "wizard_complete";
  let extraData = { exampleFieldForTesting: 1 };
  Shopify.analytics.publish(`katalys:${eventName}`, extraData)
</script>

For example, if you wish to send the event named wizard_complete, then use the following code.

HTML

<script>Shopify.analytics.publish('katalys:wizard_complete')</script>

Validating Events are Recorded

After you have installed the Katalys Shopify App and deployed code that runs custom events, you will be able to see those events within your browser’s “Network” tab.

Open your browser’s Developer Console, and select the “Network” tab.
Refresh the page or run your functionality that triggers the Katalys event.
Look for a ping to the path _tr containing your data in the “Payload” section. The host should be db.revoffers.com.

Alternative Approach

If you are using the Katalys Shopify App from the Shopify marketplace, you have an additional tracking option that will put your Katalys script directly onto your website. This makes the Katalys JavaScript API fully available to you; this might be required for some custom integrations where accessing the Katalys API directly is necessary to build your functionality. To turn on this functionality, install the Katalys script block.

How to Enable the Block

Install the public app from Shopify.
After installation, manually go to the URL: https://shop-app.katalys.com/inject-script
The app will open Online Store → Themes → Customize page.
In the theme customizer, locate App embeds or App blocks.
Add the block Katalys Event Tracker to the theme (usually under <body>).
Save changes. The recorder will now be injected into all storefront pages.

After enabling the Katalys Event Tracker block, you can use the Katalys API as normal.

HTML

<script>_revoffers_track.push('wizard_complete')</script>

How to verify it works

In Customize (design mode), a small badge appears: “Katalys Event Tracker.”
On any storefront page, check the network tab for a request to https://db.revoffers.com/js/{trackingId}.js.

How to Disable the Extra Recorder

Navigate to Online Store → Themes → Customize.
Locate the Katalys Event Tracker app block.
Disable or remove the block.
Save changes. The script will no longer be injected.