The SearchAtlas Shopify Add-on connects your Shopify storefront to Search Atlas, letting you inject and verify the OTTO Pixel, run diagnostics, and sync core SEO data — all from a single, user-friendly interface. Modern Shopify apps should use theme app extensions instead of manually editing theme.liquid, and the add-on follows that best practice.

## **🧩 Who Uses the Add-on**

- **Merchants and site admins** install the app, enable the OTTO Pixel, and run diagnostics.
- **Agencies and SEOs** verify that OTTO is firing, troubleshoot duplicate pixels, and monitor deployments.
- **Developers** maintain app code, handle webhooks, and build new blocks or endpoints.

## **🚀 Key Features**

- One-click pixel injection using Shopify's ScriptTag API or theme app embeds
- Automatic diagnostics that detect duplicate pixels, confirm correct load location, and run re-scans
- Theme App Extension support (Online Store 2.0) — enable or disable from Customize Theme → App embeds
- Secure OAuth and scoped API access to Shopify resources
- Telemetry and logging for pixel fires, detection method, last scan, and error codes

## **📥 Getting Started**

Most merchants install the add-on directly from the Shopify App Store: click Install app, complete the OAuth flow, and the app injects the pixel via the theme app embed (recommended) or the ScriptTag API. Agencies distributing to multiple stores can also use a private Custom App with the same feature set, distributed via an install link.

Developers can scaffold and test the add-on locally using the Shopify CLI and the official Shopify Remix app template, running a dev tunnel to authenticate and test ScriptTags and app embeds in a development store.

## **🏛️ How It Works**

After a merchant installs the app and completes OAuth, the app stores the shop token and offers a toggle to enable the OTTO Pixel. It then either creates a ScriptTag or activates an App Embed (theme app extension), so the pixel loads on every page. Search Atlas can then detect, validate, and deploy OTTO fixes.

When a merchant uninstalls the app, a webhook cleans up ScriptTags and marks the Search Atlas project inactive. When a merchant publishes a new theme, Shopify turns the app embed off until it's re-enabled, so a re-check after any theme change is recommended.

## **🧯 Troubleshooting**

**Pixel not firing** — open your browser's developer tools, go to Network, and search for sa-dynamic-optimization. If it's missing, check whether the app embed is disabled or the ScriptTag was deleted.

**Duplicate pixels** — look for two or more network calls to the pixel script. Choose one installation method (app embed or ScriptTag) and remove the other.

**CSP or blocking** — some themes or proxies block external scripts; whitelist Search Atlas domains or use Shopify's hosted asset.

**Theme switch or publish** — after publishing a new theme, re-enable the app embed, since Shopify disables it by default until you turn it back on.

## **❓ Merchant FAQ**

**Why do I still see a Pixel not installed message?** Re-scan in OTTO, clear your CDN cache, and make sure the app embed is on.

**Can I keep the pixel if I uninstall the app?** It's technically possible via ScriptTag, but it's not supported — the add-on removes it on uninstall for data integrity.

**Why did it break when I changed themes?** App embeds must be re-enabled after a theme publish.

The SearchAtlas Shopify Add-on gives you a repeatable, low-maintenance way to get OTTO live on any Shopify storefront, with built-in diagnostics and duplicate protection so your pixel stays correctly installed as your theme evolves.

If you need further assistance, open the chat widget in the bottom-right corner of the platform and type **human teammate** to be connected with a member of our team.