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.
| What | Looks like |
|---|---|
| Shop key | jgo_2f2dd7af34f47d6208facc82 |
| Allowed origins | https://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
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.
| Field | Why we need it |
|---|---|
id | Unique product identifier |
title | Product name |
link | The product page URL: this is how we match a page to a product |
image_link | Product image |
price | With currency, e.g. 248.00 USD |
availability | in stock / out of stock |
brand | Brand name |
description | What the companion draws on to answer questions |
Add item_group_id, size and color if your products have variants.
Check this one
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
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.appAdd 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.
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
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.
Consent
Off by default
Tell Jingo when your consent banner resolves:
jingo('consent', true) // shopper accepted analytics
jingo('consent', false) // shopper declinedOr set a global that Jingo reads on its own:
window.__consent = { analytics: true }If you use a CMP: OneTrust, Cookiebot, Osano: you'll need to add Jingo to your vendor list. At larger companies that takes longer than the code does, so start it early.
Who handles consent
You are responsible for collecting shopper consent on your storefront, through your own banner or CMP. Jingo does not show a consent banner and does not decide whether consent is required. We act only on the signal you send us.
On Shopify, the Jingo app reads Shopify's customer privacy settings and passes the result through automatically. On a custom storefront there is no equivalent layer, so you must call jingo('consent', true | false) yourself when the banner resolves. If you never call it, no events are sent.
Consent also decides whether Jingo can earn credit for a sale on a custom storefront. Before consent, the products a shopper saw a take on are kept in page memory only. After jingo('consent', true), they are saved on the shopper's device for 7 days and sent with their purchase. jingo('consent', false) stops events and deletes that list.
If you have decided your markets don't need consent for analytics, call jingo('consent', true) on every page. That decision is yours to make with your own legal advice, not Jingo's. Your privacy notice should name Jingo as an analytics provider; What data Jingo collects below lists what to disclose.
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.
| Event | Sent by | Fields |
|---|---|---|
product_viewed | Automatic | productId or handle, productTitle, variantId, variantTitle, price, currency |
search_submitted | You | query, resultProductIds |
product_added_to_cart | You | productId, handle, productTitle, variantId, variantTitle, quantity, price, currency |
collection_viewed | You | collectionId, collectionTitle, resultProductIds |
checkout_started | You | productIds, totalPrice, currency |
purchase | You | orderId, 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 tojingo('track', …)is sent as-is. currencyis a 3-letter ISO code.queryandcollectionTitlecan be at most 200 characters: a longer one is rejected, not trimmed. Only the first 10productIdsof a checkout are kept.- IDs must match the
idin your feed, or we can't resolve them. - Each entry in
linesis{ productId, variantId, quantity, lineTotal }.productIdis required;lineTotalis what the shopper paid for that line after discounts. Up to 50 lines per order.
Why purchase needs an order id
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
Checking it works
Add ?jingo_debug=1 to any product page URL. Jingo logs what it's doing to the browser console.
| What you see | What it means |
|---|---|
no slot found | The div isn’t on the page. Check it’s on the product template, not just one page. |
nothing identifiable | No canonical URL and no JSON-LD sku. Declare it with jingo(‘page’, …). |
not a product page | Jingo doesn’t think this is a PDP. Declare it explicitly. |
| Nothing in the console at all | The script isn’t loading. Check your CSP, and that the tag is in the rendered HTML. |
| Works live, not on staging | Your staging domain isn’t in the allowed origins list. Send it to us. |
| No events arriving | Consent hasn’t been granted. See step 5. |
| Renders, but doesn’t know the product | It’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.
| What | Why | How long we keep it |
|---|---|---|
| Your product catalog | To recognise products and recommend from your range | Until you ask us to remove it |
| A random visitor ID | To link one shopper’s events together, without knowing who they are | With their events |
| Shopper events, after consent | Product views, searches, cart adds, checkouts and purchases (see the event reference above), plus reactions to takes. Used for personalised takes and your analytics | About 13 months |
| What shoppers type to Jingo | Search text and questions to the assistant, so Jingo can answer. Processed by our AI providers to write the reply | Search 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 Shopify | Order ID, fulfillment status and tracking only, to keep orders placed through Jingo up to date | 30 days |
| Orders Jingo contributed to | Order 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 reporting | Until your account is deleted. The raw Shopify order message is kept 30 days |
| Products a shopper saw a take on | Product IDs and which companion spoke, on the shopper’s device, so a later purchase can be credited | 7 days on the device, cleared after a purchase |
| IP address and browser type | Sent with every web request, as on any website. Used for security and debugging | In 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.
| Column | What it holds |
|---|---|
occurred_at | When it happened, in UTC |
visitor_id | The visitor ID from your storefront, so you can join it to your own analytics |
event | What 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_id | Your product ID, with its title, variant, quantity, price and currency |
search_or_collection | What the shopper searched for, or the collection they browsed |
persona | Who gave the take: one of your personas, the store assistant, or “Shoppers’ friends” |
order_id | With 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
Reference
Script tag attributes
| Attribute | Required | Description |
|---|---|---|
data-jingo-shop | Yes | Your shop key |
data-jingo-api | No | Override the API origin, for testing |
data-jingo-debug | No | Set to 1 to always log |
JavaScript API
| Call | Description |
|---|---|
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 |