Upgrading to Theme App Extensions

If your store is using the legacy Script Tag integration, this guide will help you upgrade to Theme App Extensions for better performance and reliability.

Why Upgrade?

Script Tags (Legacy)

  • Older integration method
  • Scripts injected via Shopify API
  • Can conflict with other apps
  • Less control over loading behavior

Theme App Extensions (Modern)

  • Shopify's recommended approach
  • Better performance and caching
  • No script conflicts
  • Easy management through theme editor
  • Survives theme updates

Before You Begin

Check Compatibility

Theme App Extensions require an Online Store 2.0 theme. Most modern Shopify themes support this.

Not sure? Look for "App embeds" in your theme editor's settings.

What Gets Migrated

When you upgrade:

  • ✅ All historical data preserved
  • ✅ Settings remain unchanged
  • ✅ Visitor profiles intact
  • ✅ Recordings still accessible
  • ✅ Access control rules kept

What Changes

  • New recording method (TAE instead of Script Tag)
  • Need to enable extension in theme
  • Slightly different technical implementation (same functionality)

Upgrade Steps

Step 1: Initiate the Switch

  1. Go to Settings > Integration Method
  2. You'll see "Script Tags" with a "Legacy" badge
  3. Click Switch to Theme App Extensions
  4. Wait for the process to complete

Step 2: Enable in Theme

  1. Click Open Theme Settings
  2. In the theme editor, find App embeds section
  3. Locate ReplayPRO Recorder
  4. Toggle it to ON
  5. Click Save

Step 3: Verify

  1. Return to ReplayPRO
  2. Click Check Status
  3. You should see "Theme App Extension is enabled and working correctly"
  4. Status badge should show "Active"

Step 4: Test

  1. Open your store in a new browser/incognito window
  2. Browse a few pages
  3. Return to ReplayPRO
  4. Check Visitors for your test session
  5. Verify recording is captured

Troubleshooting

Switch Button Not Working

If the switch fails:

  1. Refresh the page
  2. Try again
  3. Contact support if persistent

Extension Not Appearing in Theme

If you don't see ReplayPRO in App embeds:

  1. Ensure your theme is Online Store 2.0 compatible
  2. Refresh the theme editor
  3. Check for any theme customizations blocking apps

Status Shows "Pending" After Enabling

  1. Make sure you clicked "Save" in theme editor
  2. Wait a few seconds
  3. Click "Check Status" again
  4. Clear browser cache if needed

Recordings Not Working After Upgrade

  1. Verify extension shows "Active" status
  2. Check that recording is enabled in Settings
  3. Test in incognito/private browsing
  4. Clear your store's cache
  5. Wait 5-10 minutes for processing

Rollback (If Needed)

If you experience issues, you can return to Script Tags:

  1. Contact support for assistance
  2. We'll help assess the issue
  3. Rollback if necessary (not recommended long-term)

Note: We don't provide a self-service rollback to encourage adoption of the better integration method.

FAQ

Will I lose any data?

No. All your data is preserved during the upgrade.

Will there be any downtime?

Minimal. There may be a brief gap (seconds to minutes) during the transition.

Do I need to update my theme code?

No. Everything is managed through the theme editor's App embeds section.

Will this affect other apps?

No. Theme App Extensions are isolated from other apps and scripts.

What if my theme doesn't support App embeds?

You can continue using Script Tags, or consider upgrading to an Online Store 2.0 theme.

Can I switch back to Script Tags?

While technically possible, we recommend staying with TAE. Contact support if you have specific concerns.

After Upgrading

Once you've successfully upgraded:

Monitor Performance

  • Check that sessions are being recorded
  • Verify analytics are updating
  • Watch a few recordings to confirm quality

Clean Up

If you had any manual script additions (from older installations), you can remove them:

  • Check your theme's theme.liquid  file
  • Remove any ReplayPRO-related scripts if present
  • The extension handles everything now

Enjoy the Benefits

  • Faster page loads
  • More reliable recording
  • Easier management
  • Better theme compatibility

Getting Help

If you encounter issues during the upgrade:

  1. Check Status - Verify what the current state is
  2. Review this guide - Ensure all steps were followed
  3. Contact Support - We're here to help

Include in your support request:

  • Your store URL
  • Current integration status
  • Error messages (if any)
  • Steps you've taken
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us