Theme Integration
Learn how LinkSpot integrates with your Shopify theme through the app embed block, theme compatibility, and metafields.
Overview
LinkSpot integrates with your Shopify storefront through a theme app embed block. This block loads automatically on product pages and renders interactive elements (Pins, Product Sets, Annotations, Captions) on your product gallery images. No theme code modifications are needed.
App Embed Block
The app embed block is the core of LinkSpot's integration with your theme. It must be enabled for any elements to appear on your storefront.
Enable the Block
From the LinkSpot dashboard, click Enable app embed to open the theme editor with the LinkSpot block selected.
Save in Theme Editor
Ensure the block is toggled on, then click Save in the theme editor.
Confirm in LinkSpot
Return to the LinkSpot dashboard and click Confirm activation. The status should change to "Enabled".
App embed blocks are deactivated by default after app installation. You must manually enable it in the theme editor. If you switch themes, you'll need to enable the block again on the new theme.
What the App Embed Does
When enabled, the app embed block:
-
Loads LinkSpot's scripts and styles on product pages
-
Reads element data from product metafields
-
Renders Pins, Product Sets, Annotations, and Captions on the product gallery images
-
Handles product card interactions (popup, new tab)
Theme Compatibility
LinkSpot needs to identify your theme's product image gallery structure to place elements on the correct images. The compatibility test automates this detection.
Running the Test
Start Test
Click Setup compatibility in the LinkSpot dashboard. A new window opens with your storefront.
Automatic Detection
The test analyzes your theme's product page and detects the gallery image elements. This takes a few seconds.
Review Results
A Compatible badge means your theme is supported and you're ready to go.
If Your Theme Is Incompatible
If the test reports your theme as incompatible, elements cannot be placed on product images automatically. You have two options:
Set a custom CSS selector that matches the product gallery items in your theme. For example: .product-gallery .gallery-item.
-
Click Manually set CSS selector from the compatibility menu
-
Enter the CSS selector for your product gallery items
-
Click Save selector
If you're unsure which CSS selector to use, contact LinkSpot support. We can help configure compatibility for your theme.
If you change themes, you'll need to run the compatibility test again for the new theme.
Multiple Themes
LinkSpot stores compatibility data per theme. Use the theme selector in the dashboard to switch between themes and run compatibility tests for each one separately.
Data Storage
LinkSpot stores element data in Shopify product metafields. These are managed automatically and you don't need to edit them directly.
On the Scale plan, you can assign a product set to individual products using the LinkSpot Product Set metafield. This allows per-product control over which product set appears, in addition to the standard targeting rules (all products, collections, specific products).
Shopify Permissions
LinkSpot requires the following Shopify access scopes:
| Scope | Purpose |
|---|---|
read_products | Read product data and images |
write_products | Write element data to product metafields |
read_themes | Detect theme compatibility |
write_themes | Enable the app embed block |
write_files | Upload images and SVG assets |
Next Steps
Last updated Mar 9, 2026
Built with Documentation.AI