Developer guide

Adding Jingo to your storefront

Jingo is a shopping companion that appears on your product pages. It knows your catalog, answers shopper questions, and recommends from your own range. The integration is one script tag, one empty div, and a product feed URL: on any platform. Budget about an hour.

Before you start

You need two things, both on your Jingo dashboard.

WhatLooks like
Shop keyjgo_2f2dd7af34f47d6208facc82
Allowed originshttps://acme.com

Your shop key is not a secret: it sits in a public script tag on a public page. What protects your store is the allowed origins list: Jingo only renders on domains you have registered.

Staging

Ask for a second key rather than reusing production. Two keys keep staging traffic out of your live analytics, and untangling them later is painful.
01

Send us your product feed

Jingo can't recommend products it hasn't seen, so this comes first. Send us a product feed URL: if you already advertise on Google Shopping, that same URL is fine. We accept Google Merchant Center XML or CSV, and poll it hourly.

FieldWhy we need it
idUnique product identifier
titleProduct name
linkThe product page URL: this is how we match a page to a product
image_linkProduct image
priceWith currency, e.g. 248.00 USD
availabilityin stock / out of stock
brandBrand name
descriptionWhat the companion draws on to answer questions

Add item_group_id, size and color if your products have variants.

Check this one

A Google Shopping feed is usually the advertisable subset of a catalog: it commonly excludes out-of-stock items. Anything missing from the feed won't be recognised when a shopper lands on its page. If yours is filtered, send us an unfiltered version.
02

Add the script tag

Put this in your site's global template so it loads on every page. The footer is fine. Google Tag Manager works identically.

<script async src="https://cdn.jingo.app/embed/loader.js"
        data-jingo-shop="YOUR_SHOP_KEY"></script>

That's the whole installation. It loads asynchronously and blocks nothing.

Don't pin a version

We ship fixes by replacing the file behind that path. Adding a version number to the URL means you stop receiving them.

Content Security Policy

If your site sends a CSP header, allow these three:

script-src  https://cdn.jingo.app
frame-src   https://api.jingo.app
connect-src https://api.jingo.app
03

Add the slot

The script needs somewhere to render. Put an empty div on your product page template, wherever you want the companion : under the buy button is the usual spot.

<div id="assistant-slot"></div>

It has no styles of its own and fills the width of its container. The companion renders in an iframe inside it, so your CSS can't break it and it can't break your page. data-jingo-slot works too if an id is inconvenient.

At this point you're live. Load a product page and the companion should appear.

04

Tell us which product

By default Jingo works out which product a page shows from the last part of the page's <link rel="canonical"> URL, matched against the last part of your feed's link field, and then from the sku in the schema.org/Product JSON-LD block, matched against your feed's id.

That's enough on most stores. If your pages have no canonical tag, or your JSON-LD has no sku, say so explicitly:

<script>
  window.jingo = window.jingo || function () {
    (jingo.q = jingo.q || []).push(arguments)
  }

  jingo('page', { type: 'pdp', productId: 'OV-MRS-0142' })
</script>

The first two lines are a queue stub: include them once, above any jingo() call. They let you call jingo() before the script has loaded; the calls replay once it does. productId should match the id in your feed.

If we can't identify it

Jingo renders nothing. That's deliberate: a companion confidently discussing the wrong product on your storefront is worse than no companion at all.

Single-page storefronts

If selecting a size or colour changes the URL without a page reload, Jingo picks it up automatically: it watches pushState, replaceState and popstate. Nothing for you to do.

Tracking shopper actions

One event is automatic: product_viewed, sent whenever the companion identifies a product page. The rest you send as they happen.

jingo('track', 'product_added_to_cart', {
  productId: 'OV-MRS-0142',
  variantTitle: 'US 4 / Ink & Ivory',
  quantity: 1,
  price: '248.00',
  currency: 'USD'
})

jingo('track', 'search_submitted', {
  query: 'silk dress',
  resultProductIds: ['OV-MRS-0142', 'CO-INS-0088']
})

jingo('track', 'checkout_started', {
  productIds: ['OV-MRS-0142'],
  totalPrice: '248.00',
  currency: 'USD'
})

jingo('track', 'purchase', {
  orderId: 'ORD-5521',
  orderTotal: '248.00',
  currency: 'USD',
  lines: [
    { productId: 'OV-MRS-0142', quantity: 1, lineTotal: '248.00' }
  ]
})

Event reference

The loader adds clientId, shop and consentGranted to every event, and seen (the products whose take the shopper saw) to purchase: you never send those yourself. Bold fields are required; an event without one is dropped.

EventSent byFields
product_viewedAutomaticproductId or handle, productTitle, variantId, variantTitle, price, currency
search_submittedYouquery, resultProductIds
product_added_to_cartYouproductId, handle, productTitle, variantId, variantTitle, quantity, price, currency
collection_viewedYoucollectionId, collectionTitle, resultProductIds
checkout_startedYouproductIds, totalPrice, currency
purchaseYouorderId, orderTotal, currency, lines

Field formats

  • Prices are numeric strings: "248.00", not "$248.00". The loader normalises what it reads from JSON-LD; what you pass to jingo('track', …) is sent as-is.
  • currency is a 3-letter ISO code. query and collectionTitle can be at most 200 characters: a longer one is rejected, not trimmed. Only the first 10 productIds of a checkout are kept.
  • IDs must match the id in your feed, or we can't resolve them.
  • Each entry in lines is { productId, variantId, quantity, lineTotal }. productId is required; lineTotal is what the shopper paid for that line after discounts. Up to 50 lines per order.

Why purchase needs an order id

We deduplicate on it. Confirmation pages get refreshed, bookmarked and reopened, and every one of those fires your tag again: we would rather miss an order than count one three times.

How a sale is credited

Send lines with every purchase: credit is given per product, not per order. Each line is:

  • Assisted if the shopper saw Jingo's take on that product, or played its voice note or reacted to it, in the 7 days before the order.
  • Not credited otherwise.

The order as a whole is assisted if any line is, and halo if the shopper only engaged with Jingo on other products. Your analytics report the credited lines' revenue separately from the full order value, so a $20 credited item in a $300 basket counts as $20. Credit needs consent: see step 5.

Same events as Shopify

Jingo's Shopify app sends this exact payload shape to this exact endpoint. The backend can't tell the two apart, so everything the companion learns from a Shopify store it learns from yours, on the same terms.

Checking it works

Add ?jingo_debug=1 to any product page URL. Jingo logs what it's doing to the browser console.

What you seeWhat it means
no slot foundThe div isn’t on the page. Check it’s on the product template, not just one page.
nothing identifiableNo canonical URL and no JSON-LD sku. Declare it with jingo(‘page’, …).
not a product pageJingo doesn’t think this is a PDP. Declare it explicitly.
Nothing in the console at allThe script isn’t loading. Check your CSP, and that the tag is in the rendered HTML.
Works live, not on stagingYour staging domain isn’t in the allowed origins list. Send it to us.
No events arrivingConsent hasn’t been granted. See step 5.
Renders, but doesn’t know the productIt’s missing from the feed, or its link doesn’t match the page’s canonical URL.

What data Jingo collects

Only what the companion needs to work, and none of it identifies a shopper by name.

WhatWhyHow long we keep it
Your product catalogTo recognise products and recommend from your rangeUntil you ask us to remove it
A random visitor IDTo link one shopper’s events together, without knowing who they areWith their events
Shopper events, after consentProduct views, searches, cart adds, checkouts and purchases (see the event reference above), plus reactions to takes. Used for personalised takes and your analyticsAbout 13 months
What shoppers type to JingoSearch text and questions to the assistant, so Jingo can answer. Processed by our AI providers to write the replySearch text with its event. The live conversation for a few hours, and a record of AI requests for quality and cost monitoring
Order updates from ShopifyOrder ID, fulfillment status and tracking only, to keep orders placed through Jingo up to date30 days
Orders Jingo contributed toOrder ID, time, currency, order total, and per line the product, quantity, amount paid and how Jingo is credited. No customer details. Used for your sales reportingUntil your account is deleted. The raw Shopify order message is kept 30 days
Products a shopper saw a take onProduct IDs and which companion spoke, on the shopper’s device, so a later purchase can be credited7 days on the device, cleared after a purchase
IP address and browser typeSent with every web request, as on any website. Used for security and debuggingIn our server logs

We never collect shopper emails, phone numbers, addresses or payment details, and the only shopper names we hold are reviewer names you include with product reviews in your catalog. If a shopper types one of those into search or the assistant, it reaches us as part of their message, and we treat it as that message: we never pull it out or use it to identify them.

On a custom storefront the visitor ID lives in localStorage on your domain under _jingo_cid, and we set no cookies. It is created on the first page load, before consent, because the companion uses it to keep a conversation together; nothing is sent with it until consent. Safari keeps it for about seven days, which is a browser limit rather than a choice of ours. The products a shopper saw a take on are stored under _jingo_seen, only after consent. On Shopify, the visitor ID is Shopify's own, which the Jingo app copies into a first-party _jingo_cid cookie, and the products seen or added through Jingo travel on the cart as hidden attributes, so they reach the order.

Exporting your data

The shopper activity Jingo records on your storefront is yours to take. On the Analytics page, pick a date range, then click Export CSV. You get one row per event in that range, and one row per visitor and product they viewed, with a view_count. Pick a campaign first to export only that campaign's take activity.

ColumnWhat it holds
occurred_atWhen it happened, in UTC
visitor_idThe visitor ID from your storefront, so you can join it to your own analytics
eventWhat happened: a product viewed, a take shown, viewed, agreed or disagreed with, a voice note played, a search, a collection viewed, a cart add, a checkout, a purchase
product_idYour product ID, with its title, variant, quantity, price and currency
search_or_collectionWhat the shopper searched for, or the collection they browsed
personaWho gave the take: one of your personas, the store assistant, or “Shoppers’ friends”
order_idWith order_total, for purchases you send us

The file holds no names, emails or addresses, because Jingo never collects them. A shopper's own friends appear only as a group, never by name.

Export regularly

Jingo deletes storefront events after about 13 months. If you want a longer history, export it before then.

Reference

Script tag attributes

AttributeRequiredDescription
data-jingo-shopYesYour shop key
data-jingo-apiNoOverride the API origin, for testing
data-jingo-debugNoSet to 1 to always log

JavaScript API

CallDescription
jingo('page', { type, productId })Declare what this page shows
jingo('track', event, payload)Send a shopper event
jingo('consent', bool)Set analytics consent
jingo('getClientId', fn)Read the visitor ID
Stuck? Email your Jingo contact with your shop key and a product page URL. Turn on ?jingo_debug=1 before you send a console screenshot: it tells us in one look what's happening.