Embedded widgets and placeholders

10 min

An embedded widget appears inside your page content instead of floating over it: an inline sign-up form at the end of a blog post, a banner on product pages, a product recommendation block in the cart. You decide where it goes with an embed code, a reusable placeholder, a Shopify app block or a WordPress shortcode. Embedded widgets use the same elements, rules, automations and A/B testing as other widgets.

Available on: all platforms. Shopify app blocks need an Online Store 2.0 theme; shortcodes need the Personizely WordPress plugin.

How it works

You mark a spot on your page, either with the widget's embed code or with a placeholder (see below).

The widget needs a trigger, like any other widget. Landing shows it as soon as the page is ready; a Scroll or Time trigger reveals it later.

When the trigger fires, Personizely looks for the spot. If it isn't on the page yet, for example because your theme renders it later, Personizely waits up to 5 seconds for it to appear.

The widget replaces the spot's content. Anything inside the target element is removed and the widget is inserted in its place, taking the width of that element.

If the spot doesn't appear in that time, the widget isn't shown on that page view and no view is recorded.

In the builder, open the widget's Settings tab and choose Placement:

Placement	What you add to your site	Best for
Embeddable code (default)	<div data-ply-embedded-widget="WIDGET_ID"></div>, shown in the Code box under Placement	One widget in one spot
A placeholder	The placeholder's code, or nothing if the placeholder has a CSS selector	A spot you'll reuse for different widgets over time, or a spot you can't edit by hand

Embed code

Copy the code from the Code box and paste it into your theme, page builder or CMS where the widget should appear. The number is the widget's ID.

<div data-ply-embedded-widget="5521"></div>

Placeholders

A placeholder is a named spot on your site that any embedded widget can use. You add it to your theme once, then choose it in a widget's Placement setting. Swapping the widget later doesn't require touching the theme again.

Go to Settings → Placeholders and click Add placeholder.

Enter a Name, such as "Blog footer".

Either leave CSS selector (optional) empty and add the placeholder's code to your site:

<div data-ply-placeholder="42"></div>

or enter a CSS selector, such as .product-detail .description, to use an element that's already on your pages. No code change is needed.

In the widget's Settings tab, choose the placeholder under Placement.

When a placeholder has a CSS selector, the widget goes into the first element on the page that matches it, and the data-ply-placeholder markup isn't used.

The widget replaces the content of the element it goes into. With a CSS selector, pick an empty wrapper or an element you're happy to replace, not an element with content you need, such as the product description itself.

Shopify app blocks

With the Personizely app installed, two blocks are available in the Shopify theme editor (Online Store → Themes → Customize), under Apps when you add a block to a section:

Block	Setting	What it inserts
Embedded widget	Widget ID	That widget's embed code
Placeholder	Placeholder ID	A placeholder's code

Add the block where the widget should appear, enter the ID and save the theme.

WordPress shortcodes

The Personizely WordPress plugin adds two shortcodes you can use in posts, pages and widget areas:

[ply-widget 5521]
[ply-placeholder 42]

[ply-widget ID] inserts a widget's embed code. [ply-placeholder ID] inserts a placeholder.

Configuration

Option	What it does	Values / default
Placement	Where the widget is inserted	Embeddable code, or one of your placeholders
Width / Height	Widget size inside its container	Auto: fills the container's width, height fits the content
Overflow	What happens to content larger than the widget	Default hidden
Margin	Space around the widget	0–100 px
Background, border, radius, shadow	Widget surface	From your branding, without shadow

Behavior details and limitations

No close button, Esc, teaser, backdrop or animation. An embedded widget stays until the visitor navigates away or an action closes it (a button set to Close widget, or a close trigger).

One spot per widget. If the code or selector matches several elements, only the first one gets the widget.

One widget per spot. If two widgets that target the same spot show on the same page, the second replaces the first, and both record a view. Use rules so only one of them can show on a given page, or test them as variations of one widget.

Control groups keep the original content. In a widget A/B test, visitors in the control group see the spot's existing content, as if the widget weren't there.

The widget appears after the page is ready, so content below it can move down when it's inserted. To avoid layout shift, give the spot a fixed min-height in your theme.

Changing steps scrolls the widget into view if the new step would otherwise be off-screen.

Embedded widgets inherit more of your site's CSS than floating widgets, because they sit inside your content. Override unwanted styles in the widget's custom CSS.

Single-page apps: if your storefront changes pages without a reload, the spot must appear on the new page within 5 seconds of the page change.

Examples

Inline blog sign-up: a placeholder with the selector article .post-content won't work because it would replace the post. Instead, add <div data-ply-placeholder="42"></div> after the post content in your blog template, and show a list-building widget there with a Landing trigger.

Product page trust banner (Shopify): add the Placeholder app block under the add-to-cart button. Run an embedded widget there on product pages with a free-returns message, and A/B test the copy.

Cart cross-sell: an embedded widget with a products element in a placeholder on /cart, showing products based on cart items.

Troubleshooting

The widget never appears → the spot isn't on the page within 5 seconds of the trigger, or the widget ID or placeholder ID in the code is wrong. Check the page source for the data-ply-embedded-widget or data-ply-placeholder element, or test the selector with document.querySelector('<selector>') in the console.