# Adding Jingo to your storefront

> Developer guide for installing the Jingo shopping companion on any storefront: one script tag, one empty div, and a product feed URL. Budget about an hour. Shopify stores can install the Jingo app instead.

Jingo is a shopping companion that appears on your product pages. It knows your catalog, answers shopper questions, and recommends from your own range.

## Before you start

You need two things, both on your Jingo dashboard:

| What | Looks like |
| --- | --- |
| Shop key | `jgo_2f2dd7af34f47d6208facc82` |
| Allowed origins | `https://acme.com` |

The shop key is not a secret: it sits in a public script tag. What protects the store is the allowed origins list: Jingo only renders on registered domains. Use a separate key for staging so staging traffic stays out of live analytics.

## 1. Send us your product feed

Send a product feed URL. A Google Shopping feed works. Jingo accepts Google Merchant Center XML or CSV and polls it hourly.

| Field | Why |
| --- | --- |
| `id` | Unique product identifier |
| `title` | Product name |
| `link` | Product page URL: how a page is matched 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` for variants. Google Shopping feeds often exclude out-of-stock items; products missing from the feed are not recognised, so send an unfiltered feed if yours is filtered.

## 2. Add the script tag

Put this in the global template so it loads on every page (footer or Google Tag Manager are fine). It loads asynchronously and blocks nothing. Do not pin a version: fixes ship by replacing the file at this path.

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

If the site sends a Content Security Policy, allow:

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

## 3. Add the slot

Put an empty div on the product page template where the companion should render, usually under the buy button. It fills its container's width and renders in an iframe, so page CSS cannot break it. `data-jingo-slot` works if an `id` is inconvenient.

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

## 4. Tell us which product

By default Jingo identifies the product from the last segment of the page's `<link rel="canonical">` URL (matched to the feed's `link`), then from the `sku` in the `schema.org/Product` JSON-LD (matched to the feed's `id`). Otherwise declare it:

```html
<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. `productId` must match the feed `id`. If the product cannot be identified, Jingo renders nothing. Single-page storefronts work automatically: Jingo watches `pushState`, `replaceState` and `popstate`.

## 5. Consent

The brand is responsible for collecting shopper consent and telling Jingo the result. Jingo shows no banner and does not decide whether consent is required; it acts only on the signal it is given. Until consent is granted Jingo sends no shopper events and credits no sales; the companion still renders. Consent is collected through the brand's own banner or CMP (OneTrust, Cookiebot, Osano: add Jingo to the vendor list, under analytics). A brand that has decided its markets don't need consent calls `jingo('consent', true)` on every page; that decision is the brand's.

```js
jingo('consent', true)   // shopper accepted analytics
jingo('consent', false)  // shopper declined
// or
window.__consent = { analytics: true }
```

On Shopify, the Jingo app reads Shopify's customer privacy settings automatically.

After consent, the products a shopper saw a take on are saved on their device for 7 days and sent with their purchase; before consent they stay in page memory only. `jingo('consent', false)` stops events and deletes that list.

## Tracking shopper actions

`product_viewed` is sent automatically. Send the rest as they happen:

```js
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'] })
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' }]
})
```

The loader adds `clientId`, `shop` and `consentGranted` to every event, and `seen` (products whose take the shopper saw) to `purchase`. Required fields are in bold; an event missing 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 |

- Prices are numeric strings (`"248.00"`, not `"$248.00"`). `currency` is a 3-letter ISO code.
- `query` and `collectionTitle` max 200 characters (longer is rejected). Only the first 10 checkout `productIds` are kept.
- IDs must match the feed `id`. Purchases are deduplicated on `orderId`.
- Each `lines` entry is `{ productId, variantId, quantity, lineTotal }`; `productId` is required, `lineTotal` is the amount paid after discounts, up to 50 lines.
- The Shopify app sends the same payloads to the same endpoint.

### How a sale is credited

Credit is per product line. A line is **assisted** if the shopper saw Jingo's take on that product, played its voice note or reacted to it in the 7 days before the order; otherwise it is not credited. The order is assisted if any line is, and **halo** if the shopper only engaged with Jingo on other products. Credited line revenue is reported separately from full order value. Credit requires consent.

## Checking it works

Add `?jingo_debug=1` to a product page URL to log to the console.

| What you see | What it means |
| --- | --- |
| `no slot found` | The div is not on the product template |
| `nothing identifiable` | No canonical URL and no JSON-LD sku: declare with `jingo('page', …)` |
| `not a product page` | Declare the page explicitly |
| Nothing in the console | Script not loading: check CSP and that the tag is in the rendered HTML |
| Works live, not on staging | Staging domain missing from allowed origins |
| No events arriving | Consent not granted |
| Renders but doesn't know the product | Missing from the feed, or its link doesn't match the canonical URL |

## What data Jingo collects

None of it identifies a shopper by name. Jingo never collects shopper emails, phone numbers, addresses or payment details.

| What | Why | Retention |
| --- | --- | --- |
| Product catalog | Recognise products and recommend | Until removal is requested |
| Random visitor ID | Link one shopper's events anonymously | With their events |
| Shopper events (after consent) | Personalised Takes and analytics | About 13 months |
| Search text and assistant questions | Answer the shopper (processed by AI providers) | Search with its event; conversation a few hours |
| Shopify order updates | Order ID, fulfilment status, tracking | 30 days |
| Orders Jingo contributed to | Order ID, time, currency, total; per line the product, quantity, amount and credit. No customer details | Until the account is deleted (raw Shopify message 30 days) |
| Products a shopper saw a take on | Product IDs and companion, on the shopper's device, to credit a later purchase | 7 days on device, cleared after purchase |
| IP address and browser type | Security and debugging | Server logs |

On custom storefronts the visitor ID is stored in `localStorage` as `_jingo_cid` (created on first load, sent nowhere until consent), and seen products as `_jingo_seen` (only after consent); no cookies are set. On Shopify it is Shopify's visitor ID, copied into a first-party `_jingo_cid` cookie.

## Exporting your data

On the dashboard's Analytics page, pick a date range and click **Export CSV**: one row per event, plus one row per visitor and product viewed with a `view_count`. Columns: `occurred_at` (UTC), `visitor_id`, `event`, `product_id`, `search_or_collection`, `persona`, `order_id`. Export before events age out at about 13 months.

## Reference

| Script attribute | Required | Description |
| --- | --- | --- |
| `data-jingo-shop` | Yes | Shop key |
| `data-jingo-api` | No | Override the API origin, for testing |
| `data-jingo-debug` | No | Set to 1 to always log |

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

Support: email your Jingo contact with the shop key and a product page URL, with `?jingo_debug=1` console output.
