Connecting an Offer to an Offer Template
If you need to manually trigger an Offer, you will need to designate the Offer Template by placing the tp.offer.show function inside of an init callback. From a technical perspective, any Offer can be rendered inside any Offer Template.
The parameter passed to the tp.offer.show method is a JSON object that may contain the following values:
{
offerId(string, required): The ID of the offer presented to the user,
templateId(string, optional): The ID of the template being used to present the offer,
templateVariantId(string, optional): The ID of the variant of the offer template,
displayMode(string, optional): The display mode (can be "inline" or "modal"). The default is "modal",
containerSelector(string, optional): CSS selector for the container the offer should be loaded into,
termId(string, optional): The ID of the term that should be automatically selected on showing the offer,
termIds(array, optional): An array of term IDs that should be dynamically included in the offer,
promoCode(string, optional): The promo code that should be applied in checkout.
loginRequired(function, optional): callback function that will be invoked when user is required to login,
showCloseButton(boolean, optional): values true or false. Defines if the close button will be shown on the offer or not,
close(function, optional): Callback function which will be invoked when user closes this offer,
complete(function, optional): Callback function which will be invoked when user has converted on one of the terms presented in the offer,
customEvent(function, optional): Callback for custom events that happen in this offer
checkoutFlowId(string, optional): The ID of the checkout flow for passwordless checkout.
}
Here's this callback with example values:
tp.push(["init", function () {
tp.offer.show({
offerId: "O123456",
templateId: "OTWPZJ3HJKT6",
templateVariantId: "OTV8DAZJ99LP2",
displayMode: "inline",
containerSelector: "#my-inline-offer",
termIds: ["T1234", "T2345"],
promoCode: "PROMO123",
loginRequired: function () {},
showCloseButton: true,
close: function () {},
complete: function (params) {},
customEvent: function (params) {}
checkoutFlowId: "CF1Q8ZCMT123",
});
}]);
The offerId is the only required parameter fortp.offer.show. The templateId parameter is optional, but recommended. Including it creates the loose coupling between the Offer and the Offer Template. If you do not include the templateId the Offer will be presented in the Default Offer Template.
The offerId can be found by going to Manage → Offers and copying the unique offerId from the Offer in question. The templateId is located under Manage → Templates → Offer.
Below is an example of how to show an offer with 2 different registration forms (one for each term):
tp.offer.startCheckout({templateId:'OT123456', offerId:'OF123456', templateVariantId:'OTV123456', formNameByTermId:'{"TM24RQEHS123":"registrationForm1", "TMYQ8FMNE123":"registrationForm2"}'})
The startCheckout method is available only when an offer template is launched using tp.offer.show or through the “Show offer” card in a Composer experience. If terms are specified directly in the HTML of the template (e.g., passed to startCheckout), those terms should be included in the Offer, either through the "Show offer" card in the Composer Experience or the offerId provided in the JavaScript function. The order of terms in the Offer does not affect functionality, and the Offer may contain more terms than are used in the template. However, any term passed to startCheckout should be defined in the associated Offer for the method to work correctly.
However, if needed you can include Terms not listed in the Offer by passing them via the termIds attribute in tp.offer.show(), as described here.
Showing Lightweight Templates
Lightweight Templates can also be rendered using tp.offer.show() by passing engine: "LIGHTWEIGHT" in the options object. For more details, see this article.
Modal vs Inline Offer Templates
When showing an Offer, you can specify whether the Offer Template is displayed as a pop-up modal/lightbox or inline on the page. If you don't pass either of the "inline" or "modal" values to the displayMode parameter, it will default to modal (a semi-transparent backdrop that takes over the entire page and places an iframe 40 pixels from the top of the page with the Offer Template inside of it).
When displaying an offer as a modal, the close button is outside of the iframe container in the upper righthand corner of the iframe and must be styled in the parent page using the following CSS selector:
.tp-modal .tp-close {
border-color: #f00;
}
To style the semi-transparent backdrop that appears when displaying an Offer in a modal, override this CSS selector:
.tp-backdrop.tp-active {
opacity: .5;
}
To display a template inline (e.g. “cutting off” a premium story or video for someone who doesn't have access), simply pass the "inline" value to the displayMode parameter. If you do this, you must specify a containerSelector as well. The containerSelector must be a valid jQuery selector (if it is not, we will display an error in the browser's console). See here for more information on how to create a container for an inline Offer Template.
Note: Checkout will always open in a modal for security reasons, even when the offer itself is displayed inline.
Dynamically Adding Terms to an Offer
You will typically determine what terms belong inside an Offer by adding those terms to that Offer inside the Piano dashboard under Manage → Offers.
However, you can dynamically pass terms to an Offer by using the termIds parameter. The termIds parameter can either be a string with a single termId or an array of termIds.
Here's an example of how this would look:
tp.push(['init', function() {
tp.offer.show({
offerId: "O123456",
templateId: "OTABCDEF",
termIds: [ "TXYZ", "TUVW" ]
});
}]);
On display, the two terms in the example above will be added at the bottom of the Offer below any terms that were been added to the Offer within the Piano dashboard. If the Offer that has been configured in the dashboard does not have any terms inside of it, only the dynamically added terms will be displayed.
Display a Specific Custom or Registration Form
You can open a specific registration or custom form for any term with this code:
tp.offer.show({
formNameByTermId: '{"<Term_ID>":"<Form_ID>"}',
offerId: '<Offer_ID>',
termId: '<Term_ID>',
displayMode: "modal",
});
Note, you'll need to hardcode all offer's terms if you need to show alternative forms for all of them.
Additional Offer Template Functions
The tp.offer object offers various helper methods to further control the offer behavior.
close
The tp.offer.close() method can be used to close the Offer if the Offer is in modal mode.
showBackdrop
The tp.offer.showBackdrop() method will show the semi-transparent backdrop.
hideBackdrop
The tp.offer.hideBackdrop() method will hide the semi-transparent backdrop.
centerBackdrop
The tp.offer.centerBackdrop() method will center the semi-transparent backdrop.
reload
The tp.offer.reload(iframeId, config) method will reload the offer config. You can use this method to solve the problem where a user logs into your site after the Piano offer template has already loaded on the page for the previously not-logged-in user.