This article is for non-Shopify merchants only.
How the Embedded signup widget fits in the customer flow
The Embedded signup widget is an iframe you paste into your storefront — typically on a dedicated "Refer a friend" page, or anywhere you want a referral signup form to appear inline. Visitors fill in the form to sign up to your campaign. If they're already enrolled, the widget switches to show their referral link and sharing options, so the same widget doubles as a way for returning advocates to get back to their referral link.
Whether anyone who submits the signup form actually becomes an enrolled advocate depends on your campaign's Target audience (segment criteria), not the widget itself — see the "Who can sign up" FAQ below.
Make it more seamless for customers already signed into their account
If your customers have accounts on your store, you can pass their email (and optionally first and last name) to the widget through data-* attributes. The widget reads those values from your store's logged-in session, so already-enrolled customers see their referral link immediately — no need to re-enter their email to access their sharing options.
This is optional, and you've got a few ways to set it up:
Public signup form — paste the default snippet on any public page (a "Refer a friend" page, your homepage, etc.). Anyone who visits enters their email to sign up. This is the simplest setup.
Pre-filled for logged-in customers — same snippet, but add
data-email(and optionallydata-fname/data-lname) and wire those values to your store's logged-in customer session. Often placed inside a customer account page (or equivalent logged-in surface) so already-enrolled customers see their referral details the moment they land on the page.Both at once — paste it on a public page AND pass the dynamic variables. Visitors who aren't logged in see the public signup form; logged-in customers automatically get the pre-filled seamless experience on the same page.
Wiring up the dynamic data-* values typically requires a developer, since it depends on your store platform's templating language or JavaScript.
For how this widget compares to your other referral surfaces (Post-purchase popup, Floating Referral Widget, Cookie consent) and which to use when, see Widgets for your referral program.
For what advocates see after signing up through the Embedded signup widget — their Share Page, the Your Rewards tab, and the authentication options for accessing rewards — see What advocates see after signing up.
Note for cash-reward campaigns: the signup email an advocate enters here becomes their default PayPal payout email. Advocates can update it later from their Rewards page — the option appears once they've earned their first cash reward.
ReferralCandy gives you the ability to host the Embedded signup widget directly on your website. The widget allows you to:
Embed an iframe for the signup form into a page on your website.
Embed a personal sharing widget to your customer's account page.
Copy the widget code snippet
You can embed the signup widget on any existing page or a dedicated page for your referral or affiliate program. This is a great way to encourage your customers to join your campaign and grow your advocate list.
Note: Your campaign must be set to Live for the Embedded signup widget to appear. Learn more
From the ReferralCandy dashboard, go to Campaigns > Select your campaign.
Go to Widgets.
In the Embedded signup section, click Copy next to the iframe code snippet. The widget uses the
refcandy-candyjariframe script.
Insert the code into your store's page by pasting it just before the HTML
</body>tag. You can also place it anywhere on your site, or add a new page dedicated to the signup widget.
Make the widget seamless for logged-in customers (optional)
If you embed the widget on a page where the customer is already signed into their store account (commonly a Customer Account Page, but any logged-in surface works), you can pre-fill the widget with their email so they go straight to their referral link without re-entering anything.
To do this, add the data-email attribute (and optionally data-fname / data-lname) to the iframe, and wire the values to your store's logged-in customer session. See attributes below.
Important: The data-email, data-fname, and data-lname values need to be generated dynamically from your store's logged-in customer session — typically using your platform's templating language or JavaScript. You'll likely need a developer to wire this up.
Two things to figure out for your platform before you start:
What your platform calls the logged-in customer's email in its templating system. For example, some platforms expose this as a Liquid/Handlebars variable, others through PHP, others through a JavaScript object on the page. Your platform's developer documentation usually covers this, or ask a developer who knows your platform.
Whether the page you want to embed on can actually access logged-in customer data. A customer account page or order confirmation page typically can; a public marketing page typically can't. If your platform is custom or unusual, your developer should be able to confirm.
If the pre-filled widget isn't working as expected after you've set this up, see the "pre-filled widget isn't showing the customer's referral link" FAQ below.
Widget attributes
You can add or change the following attributes on the iframe:
data-height: Height of the sharing panel in pixels or percentage.
data-width: Width of the sharing panel in pixels or percentage.
Note: Use 100% if you want the panel to be responsive to the width of the browser depending on screen size.
data-email (optional): The customer's email — used to pre-fill the widget so a logged-in, enrolled customer sees their referral link immediately instead of the signup form. Example:
data-email="john@example.com". See Make the widget seamless for logged-in customers above for the full setup.data-fname (optional, used with
data-email): First name of the customer. Example:data-fname="John".data-lname (optional, used with
data-email): Last name of the customer. Example:data-lname="Smith".data-locale (for accounts with multiple languages): Specify this attribute to display the widget using the correct theme based on locale. For example,
data-locale="fr".
Article FAQ
Who can sign up through the Embedded signup widget?
Who can sign up through the Embedded signup widget?
The widget itself doesn't filter who can sign up — anyone who fills in the form is routed to your campaign's enrollment logic. Whether they actually become an enrolled advocate is controlled at the campaign level (not at the widget level) via your campaign's Target audience (segment criteria).
For example, you can set Target audience to "lifetime purchase value greater than $0" to make the campaign customer-only — non-customers who submit the form would be waitlisted, not enrolled. They'll only become enrolled if and when they meet your Target audience criteria.
Cash vs discount reward — common patterns:
Cash-reward campaigns are often configured customer-only (or restricted to a more verified segment), since the merchant is paying out real money — Target audience usually filters on past purchase value.
Discount-reward campaigns are typically more open — Target audience may allow non-customer signups, since the friend offer plus the merchant's storefront does the qualifying.
Configure Target audience in your campaign settings; this logic applies to all widgets, not just Embedded signup.
Can I use this widget on multiple pages?
Can I use this widget on multiple pages?
Yes. You can paste the iframe code snippet on as many pages as you want — every instance points back to the same campaign. Just keep in mind that for the per-customer mode (with data-email), the dynamic attribute values need to be generated correctly on each page where you embed the widget.
How is the Embedded signup widget different from the Join Page?
How is the Embedded signup widget different from the Join Page?
Both are signup surfaces for your referral program, but they live in different places:
Embedded signup lives on your storefront (iframe pasted into your site's HTML). Customers stay on your domain and your branding — best when you want signups to feel native to your store.
Join Page is ReferralCandy-hosted at your campaign's "Promote your program" URL (e.g.
your-store.refr.cc/join/Customer). No site setup required — just share the link. Best for email marketing, social posts, or anywhere you want a quick link-based entry point without embedding code.
When you can run an embedded form, the Embedded signup widget is more seamless (customers don't leave your site). Reach for the Join Page when you specifically want a link to drop into a campaign email or social post without setting up code on your storefront.
The pre-filled widget isn't showing the customer's referral link — what should I check?
The pre-filled widget isn't showing the customer's referral link — what should I check?
If you've set up data-email (and optionally data-fname / data-lname) but the widget isn't recognizing the logged-in customer, the most common causes are:
Placeholder dummy values weren't replaced. The snippet from the dashboard ships with example values. Make sure those have been replaced with your platform's actual dynamic variable syntax for the logged-in customer's email and name.
The dynamic variable isn't being substituted on the page. Open your store page in a browser and View Page Source —
data-emailshould show the actual customer's email, not the variable name still in template syntax (e.g.,data-email="{{ ... }}"). If the variable name is still showing, your platform isn't substituting the value at render time — usually a templating context issue.The page doesn't have a logged-in customer context. Some pages can access logged-in customer data (customer account page, order confirmation page); public marketing pages typically can't. Test on a page you know is bound to a logged-in customer.
The customer isn't currently signed in. If they're not signed in, the widget falls back to the public signup form. That's expected behavior, not a bug.
The email doesn't match an enrolled advocate. If the customer is signed in but isn't enrolled in your campaign yet (e.g., they don't meet your Target audience criteria), the widget shows the signup form rather than a referral link. They'd need to sign up and become enrolled first.
For custom or unusual platforms, a developer familiar with your store may need to confirm that the page can read logged-in customer data and that the dynamic value is being passed correctly into the iframe attribute.