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

Migrate from the Legacy Tracking Script to the New Tracking Script (Step-by-Step)

Step-by-step migration from the Legacy Tracking Script to the New Tracking Script—what changes, UI cues, and how to switch safely.

IN THIS ARTICLE YOU WILL:

Why this matters

The Legacy Tracking Script is deprecated and projects will begin auto-migration to the new script on February 1, 2026. Migrating now ensures best performance, SPA support, and access to new capabilities.

Who should use this guide

  • Your project currently shows Use Legacy Script (toggle On) under Configuration → Environments & Tracking Code.

  • You see the Code Snippet dialog for legacy with a grey/blurred, non-copyable snippet and an information message that new installations of the legacy script are no longer permitted.

  • You’re ready to switch all new installs and updates to the New Tracking Script.

Migration steps

  1. Open your project’s script settings
    1. Go to Project → Configuration → Environments & Tracking Code.
    2. If your project is on legacy, you’ll see Use Legacy Script: On.
    3. In Install Code Snippet, both Basic and Advanced legacy snippets are blurred/locked and cannot be copied. An information message explains that new installations of the legacy script are not allowed and prompts you to switch to the new script using the Use Legacy Script control.
      lagacy1
  2. Disable the Legacy Script (one-time, permanent)
    1. Click Use Legacy Script to toggle Off.
    2. A confirmation popup appears: it explains the change is permanent and enables the Modern (New) Script. Confirm to proceed.
      1. After confirmation, the legacy toggle and its code section disappear for this project (cannot be re-enabled).
      2. For non-legacy projects, this toggle is not shown at all.
        3-1
    3. What changes immediately
      1. The Code Snippet dialog now shows the New Tracking Script (copyable).
      2. Legacy snippet install/copy paths are gone across the app (including “Don’t forget to install code” alerts and both Basic and Advanced tabs).
  3. Install the new snippet on your site
    • In Install Code Snippet, copy the New Tracking Script and paste it into your site’s <head> (right after <title> is ideal).
      Source: 

Tip: If you separate staging vs. production behavior, use Environment-Specific Global JavaScript instead of custom forks of the snippet.

Source: How to Use Environment-Specific Global JavaScript in Convert

What you’ll see in the UI (so there are no surprises)

  • Legacy snippet install disabled: The legacy Basic/Advanced tabs in Code Snippet display a blurred snippet with a grey overlay; the copy button is disabled. An information message appears:
    “New installations of the legacy tracking script are no longer permitted. Please switch to the new tracking script by toggling off the Use Legacy Script toggle.”
     The Use Legacy Script text is a link that takes you directly to Environments & Tracking Code.

  • Hidden when not applicable: If your project is not using legacy, the Use Legacy Script toggle is hidden entirely. After you toggle legacy Off, it never reappears for that project.

  • Confirmation popup: When turning legacy Off, you’ll see a confirmation dialog clarifying the change is permanent and enables the Modern Script (warning text is highlighted to signal impact).

📒 Note for Single-Page Applications (SPAs):

The new script natively supports SPAs. If your project previously implemented manual polling, pushState proxies, or run() calls from the legacy guide, remove them unless you hit a rare edge case.
Source: Running Experiments on Single Page Apps

FAQs

Can I still install or copy the legacy snippet?
 No. New installations of the legacy snippet are disabled in-app (snippet is blurred/locked and the copy button is disabled). Use the Use Legacy Script link to switch, then install the new script.

What happens after I toggle legacy Off?
 The legacy toggle and code sections disappear permanently for that project. Only the new script (and its versioning controls where applicable) remain visible.

Will my tests break?
 No action is required inside existing experiences. Just replace the snippet in your site and validate. If you had SPA workarounds from the legacy guide, remove them and test.

Where do I confirm the script was updated?
 Reopen Install Code Snippet to confirm you’re seeing the new script, and use your browser console to check convert.currentData.experiences after a page load.
Source: Reading Triggered Experiment Data for Using it in Third Party Systems