Developers
The subscribe.to embeddable widget is highly versatile and as such, can be used to create a variety of interactive experiences. If you use any of the embeddable versions provided by us, everything is taken care of and there's nothing more you need to do. Just paste the code and you're good to go. But if you are a developer and want to create your own interactive experience, we are offering a set of simple developer tools. The purpose of these tools is to improve end user experience through intelligent interactions.
The iframe
In order to work with the subscribe.to widget, you need to include the iframe in your web page:
<iframe src="https://subscribe.to/embed/my-widget-id" width="anything" height="anything" class="s2s_widget_em" style="display:block;max-width:600px;border:none;margin:5px auto;"></iframe>
You can get your widget ID here.
The iframe has two modes that toggle automatically: full (when the iframe inner width is greater than or equal to 300px) and compact, when the inner width is less than 300px. The content inside the iframe will automatically resize to fill the available space. We recommend playing with different sizes until you find the one that best fits your needs.
We recommend using the border:none style, since certain browsers automatically add borders to iframes.
Please note that the display mode (full or compact) is calculated on page load, so you won't be able to switch mode by resizing the browser window.
window.postMessage() communication
The subscribe.to iframe sends 6 different types of messages to the top parent window.
s2s_show
The default behavior of the subscribe.to modal widget is to only display if the visitor isn't subscribed to that particular email address. This is a useful feature to avoid bothering people who are already subscribed to your newsletter. For this purpose, after checking that the user hasn't already subscribed to you, the iframe sends a s2s_show message as a hint to display the widget. You shouldn't display the widget until you receive this message.
Note: in most cases, this doesn't work on Safari due to Webkit's ITP.
s2s_hide
When the user slides the slider until the end and subscribes, we send a s2s_hide message to the top parent so that the widget can be dismissed automatically. You can also use this event to create interactive experiences or give feedback after subscribing. We recommend hiding the iframe and not removing it from the DOM - this way you will still be able to receive messages like s2s_subscribed.
s2s_slide_action
We send this message when the user slides the slider until the end, regardless of whether this resulted in a subscribe action.
s2s_interacted
The interacted message is sent ontouchstart and onmousedown on the iframe body. The default behavior of the subscribe.to modal widget is to automatically hide after a certain amount of time, unless interacted with. The s2s_interacted message acts as a signal not to auto-dismiss the widget.
s2s_subscribed
When the user successfully subscribes via the iframe, we send a s2s_subscribed message to the top parent. This is useful when you really want to make sure that the user subscribed. There are two situations in which this message is sent:
- When the user is logged in and therefore instantly subscribes by sliding.
- When the user is not logged in and we need to send them a confirmation email. In this situation, we only send the
s2s_subscribedmessage once the user completes the email confirmation flow. If this takes more than 2 minutes, we no longer send the message.
s2s_awaiting_confirmation
We send this message when a user who is not logged in slides the slider.
Customizing the iframe
s2s_dark_mode_on
Send this message to the iframe to enable dark mode. Example:
let s2s_iframes = document.querySelectorAll('.s2s_widget_em');
s2s_iframes.forEach(function(e){
e.contentWindow.postMessage('s2s_dark_mode_on', 'https://subscribe.to');
});
if (typeof s2smmd !== 'undefined') {
s2smmd.classList.add('s2sdark');
}
Allowed domain
For security reasons, we only post messages to the domain that's whitelisted in the user's account. This can be changed by the user at any time.
Code example
function receiveMessage(event) {
if (event.origin !== "https://subscribe.to") {
return;
} else {
let message = event.data;
switch (message) {
case 's2s_show':
// Display the widget
break;
case 's2s_hide':
// Hide the widget
break;
case 's2s_interacted':
// Prevent the widget from auto-hiding
break;
case 's2s_subscribed':
// Yey
break;
case 's2s_awaiting_confirmation':
// Waiting...
break;
default:
// Optional, handle unexpected events
}
}
}
window.addEventListener("message", receiveMessage, false);
Guidelines
The following guidelines should be respected in all subscribe.to custom integrations.
Politeness
The widget should auto-dismiss if not interacted with for a certain amount of time. You can use the s2s_interacted event to detect user interaction inside the iframe. For interactions outside the iframe, you must create your own listeners.
Usability
A clearly visible close button must be present. Please ensure that the close button has sufficient padding so as to support imprecise clicking/tapping, especially on mobile. We use this padding value on the modal widget: padding: 17px 21px 50px 13px;. You may use a smaller value depending on the size of the close button. As a rule of thumb, the total clickable area of the close button should be at least 40x40px.
Themes
The subscribe.to embeddable form comes with two built-in themes.
Default
The default theme is enabled on all subscribe.to embeds that have a height bigger than 150px. This includes the Medium form and all other iframe-based embeddable forms. The default theme allows the form owner to customize the appearance of the widget to suit their needs. The customizations are made directly on the form itself via the widget controls in the top right corner.
Fancy
The Fancy theme is showcased on our homepage and unlike the default theme, is not customizable. You can try it out by adding ?theme=fancy to your iframe src. Example: src="https://subscribe.to/carfactory?theme=fancy".
How to promote your integration
To get valuable feedback and users, post your creations in the Community. The best ones will be featured on the main website, too.