At a Glance
First-party tracking is the foundation of Performance Infrastructure™. Without it, attribution confidence will be low across the board and Revenue Pulse will have limited data to work with. This guide walks through the complete setup in four steps.
Why first-party tracking matters
Most analytics tools rely on third-party cookies or pixel-based tracking — both of which are increasingly blocked by browsers, ad blockers, and privacy regulations. Blue Ninja uses a first-party visitor ID approach:
- 1A visitor lands on your site. Blue Ninja assigns them a first-party visitor ID stored in a first-party cookie.
- 2The visitor browses, clicks, and eventually reaches checkout.
- 3The visitor ID is passed into the Stripe checkout metadata at the moment of purchase.
- 4Blue Ninja connects the traffic source (from the visitor's first touch) to the revenue event (from Stripe) with high confidence.
This is the Truth Layer. It is the foundation of every Revenue Pulse insight.
Step 1: Install the Blue Ninja tracking script
Add the Blue Ninja tracking script to the <head> of every page on your site. The script is available in the Blue Ninja Portal under Settings → Tracking.
``html <script src="https://cdn.blueninja.systems/track.js" data-site-id="YOUR_SITE_ID" async></script> ``
Verification: After installing, visit your site in a browser and open the developer console. Run window.BlueNinja?.visitorId — if a visitor ID is returned, the script is installed correctly.
Important: The script must be present in the pre-rendered HTML of every page, not loaded dynamically after page load. If your site uses a JavaScript framework (React, Next.js, Vue), add the script to the root layout or _document file.
Step 2: Pass the visitor ID into Stripe checkout metadata
When a customer initiates checkout, pass the Blue Ninja visitor ID into the Stripe checkout session metadata. This is the critical step that enables high-confidence attribution.
For Stripe Checkout (server-side): ``javascript const session = await stripe.checkout.sessions.create({ // ... your checkout configuration metadata: { blue_ninja_visitor_id: req.cookies['_bn_vid'] || '', utm_source: req.query.utm_source || '', utm_campaign: req.query.utm_campaign || '', utm_medium: req.query.utm_medium || '', } }); ``
For Stripe Payment Intents: ``javascript const paymentIntent = await stripe.paymentIntents.create({ // ... your payment intent configuration metadata: { blue_ninja_visitor_id: req.cookies['_bn_vid'] || '', } }); ``
Verification: Complete a test purchase and check the Stripe Dashboard → Payments → [your test payment] → Metadata. You should see blue_ninja_visitor_id with a value.
Step 3: Connect Stripe to the Blue Ninja Portal
In the Blue Ninja Portal, go to Settings → Integrations → Stripe. Click "Connect Stripe" and complete the OAuth flow. Blue Ninja will request read access to your Stripe account to pull order, subscription, and refund data.
What Blue Ninja reads from Stripe:
- Charges and payment intents (with metadata)
- Subscriptions and subscription items
- Refunds and disputes
- Customer records (email and ID only — no payment card data)
What Blue Ninja does not read:
- Payment card numbers or CVVs (these are never accessible via the Stripe API)
- Bank account details
Step 4: Connect Brevo (CRM and email automation)
In the Blue Ninja Portal, go to Settings → Integrations → Brevo. Enter your Brevo API key. Blue Ninja will sync contact attributes and enable lifecycle playbook execution.
What Blue Ninja syncs to Brevo:
- Customer LTV and order count (as contact attributes)
- Segment membership (high-intent, at-risk, etc.)
- Playbook triggers (abandoned checkout, post-purchase, winback)
Step 5: Verify attribution confidence distribution
After 48–72 hours of live tracking, go to Revenue Pulse → Attribution in the Blue Ninja Portal. You should see a confidence distribution showing the percentage of revenue attributed at high, medium, and low confidence.
Healthy distribution:
- High confidence: 40–70% of revenue
- Medium confidence: 20–40% of revenue
- Low confidence: 10–20% of revenue
If high confidence is below 30%: The visitor ID is likely not being passed into Stripe metadata correctly. Re-check Step 2.
If all attributions are low confidence: The tracking script may not be installing correctly. Re-check Step 1.
Common issues
| Issue | Likely cause | Fix |
|---|---|---|
| No visitor ID in console | Script not loading | Check script tag placement and site ID |
| Visitor ID not in Stripe metadata | Metadata not being passed | Re-check server-side checkout code |
| Low confidence across all channels | Tracking or metadata issue | Run through Steps 1–2 again |
| Brevo playbooks not triggering | API key or attribute sync issue | Re-check Brevo API key and attribute mapping |