Skip to content
  • There are no suggestions because the search field is empty.

Bring Your Own ID (BYOID): Use Your visitorId in Convert

Define a custom visitorId from your stack to control bucketing, persistence, and analytics joins in Convert.

IN THIS ARTICLE YOU WILL LEARN:

What is BYOID?

Bring Your Own ID (BYOID) lets you use a stable identifier from your own stack (CRM/CDP/auth system, etc.) for bucketing and attribution in Convert. Instead of Convert issuing its own anonymous ID, your supplied visitorId becomes the identity used for experiment assignment and reporting.

Why it helps

  • Consistent identity across domains and apps (as dictated by your ID strategy)

  • Easier join with downstream analytics/warehouse data

  • Control over persistence and rotation cadence (aligned to your platform’s rules)

📒 Important:

Provide only non-PII, pseudonymous identifiers. Do not pass emails, phone numbers, full names, or other personal data.

The snippet (copy/paste)

Place this as-is, replacing 'xxx' with your own ID string:

<script>
  window._conv_q = window._conv_q || [];
  window._conv_q.push({
    what: 'identify',
    params: {
      visitorId: 'xxx' // your custom visitor id
    }
  });
</script>

Where to place the snippet (two options)

You can use either option below. Choose the one that best matches your implementation pattern.

Option A — On your website before the Convert Tracking Script

  1. Add the BYOID snippet to your page template above the Convert Main Tag.

  2. Keep it as early as possible in the <head> so the identity is known before experiences evaluate.

  3. Deploy site‑wide wherever Convert runs.

When to prefer this: You manage your site/app templates and can guarantee ordering. This is the most reliable way to ensure the ID is established before experiment bucketing.

Option B — In Project → Global JavaScript (inside Convert)

  1. Go to your Convert project settings → Global JavaScript.

  2. Paste the BYOID snippet exactly as shown.

  3. Save and publish. It will run for all experiences in the project.

When to prefer this: You can’t easily change site templates, or you want a single, centrally managed place in Convert to define the ID.

📒 Note:

If you choose Option B and your app is a fast SPA, ensure your own ID is available synchronously on first paint (e.g., from a first‑party cookie or preloaded data). If your ID becomes available later, consider re‑triggering identity (see example) before experiments run on subsequent route changes.

Practical example — reading your ID from a first‑party cookie

Below is a resilient pattern that reads a stable ID from your systems (cookie/localStorage/dataLayer) and applies it to Convert. Replace cookie key names with your own.

<script>
  // Helper: read a cookie by name
  function readCookie(name){
    return document.cookie.split('; ').find(row => row.startsWith(name + '='))?.split('=')[1];
  }

  // 1) Get your own ID from your platform
  // Try cookie → localStorage → dataLayer (customize to your stack)
  var myId = readCookie('my_uid') ||
             (typeof localStorage !== 'undefined' && localStorage.getItem('my_uid')) ||
             (window.dataLayer && window.dataLayer.find?.(e => e.userId)?.userId) ||
             null;

  // 2) If you have a valid, non-PII string, pass it to Convert
  if (myId && typeof myId === 'string') {
    window._conv_q = window._conv_q || [];
    window._conv_q.push({
      what: 'identify',
      params: { visitorId: myId }
    });
  }
</script>

Tips

  • Keep the value short, opaque, and stable (e.g., UUID or hashed user key).

  • Do not change the visitorId mid‑session. If it must change (e.g., user logs in), do it before a new page load or before new experiences evaluate to avoid re‑bucketing.

QA checklist

Use this quick list before you go live:

  • Ordering is correct. The BYOID snippet is above the Convert Main Tag (Option A) or it’s present in Project → Global JavaScript (Option B) and changes are published.

  • Active Domains are set. Your test and production hosts are added under Project Configuration → Active Websites/Domains so the script runs where you expect.

  • Debug logs show identify. Load a test page with ?convert_log_level=debug (or use the Chrome Debugger extension). Confirm an identify action is queued once and the visitorId matches your source.

  • ID is stable & non‑PII. The same visitorId persists across reloads/pages/SPA routes; it’s an opaque string (no emails/phones) and not rotated mid‑session.

  • Variant stickiness. After activation, the assigned variation remains the same across refreshes and navigation for the same visitorId.

  • Fallback behavior. If your ID isn’t available, the snippet does not send blank/invalid values; ensure your app surfaces the ID early (e.g., cookie or preloaded data).

  • Joins & analytics. Your analytics/warehouse (e.g., GA4) can join experiment results to your visitorId as intended.

  • Cross‑domain scope (if relevant). The same visitorId is available on all domains/subdomains where Convert runs, or you’ve designed per‑domain handling.

FAQ

Does BYOID replace Convert’s internal ID?
When you provide visitorId, Convert uses it for identity and bucketing in that project. Avoid sending conflicting values for the same person within a session.

Can I use BYOID on only some pages?
Yes, but for consistent results, we recommend setting it wherever the Convert script runs so the same person isn’t randomly identified differently.

What about privacy?
Only pass non‑PII identifiers (hashes/opaque IDs). Ensure your privacy notices cover this usage.

 

Related tasks in the app (inline guidance)

Where you copy your tracking script in Convert, you’ll see a short tip:

Using your own visitor ID? Paste this snippet above the Convert script on your site or add it under Project → Global JavaScript:

window._conv_q = window._conv_q || [];
window._conv_q.push({ what: 'identify', params: { visitorId: 'xxx' } });

Replace 'xxx' with a non‑PII ID from your system.

Need help?

If you’re unsure where your ID is available or how to surface it synchronously, contact our support team and we’ll review implementation options with you.