Marketing Automation (Campaign) - Reach Integration: How it works

  • Updated

Overview

The Reach package of the Personalization suite enables the Campaign client to use personalized recommendations and behavior based triggers in Email campaigns.

The triggers can be sent to active recipients in any regular recipient list. The products are referenced by image/link URLs and rendered as images by the Personalization engine based on the customers product feed.

This documentation should provide all required information of what has to be done and prepared in Campaign to use Reach recommendations. To set up the feature in Reach please follow this guide: https://webhelp.episerver.com/latest/personalization/triggers/using-triggers-with-campaign.htm

 

How it works

Recommendations - SMART Mail

For SMART Mail works by sending out URLs for product image, product description image and product landing page. These are generated as "widgets" (wid)  in REACH, where the customer sets up product recommendation strategies and gets a specific HTML recommendation snippet. This is pasted into the mailing or recommendation paragraph. For more information see below in "Integration in Mailing".

Product Urls
https://[customeraccount].peerius.com/tracker/er/link.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&date={dateFunction}
https://[customeraccount].peerius.com/tracker/er/image.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&date={dateFunction}
https://[customeraccount].peerius.com/tracker/er/productinfo.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&date={dateFunction}

The following placeholders and fieldfunctions need to be setup in the client for Smart Mail to work:

Required field functions
{recipientid}
{dateFunction}

Triggermails - SMART Trigger

The Smart Trigger works as a combination of trigger via HTTP-API sendeventmail to trigger a specific event mailing and sending out URLs for product image, product description image and product landing page in this mailing. A special code identifies the products to belong to this trigger event in the URLs (externaltriggerid). This code is set by a HTTP-API updatefields for the recipient.

In REACH the customer sets the trigger rules and product strategies and also the recipient list authorisation code (API interface) and gets a specific HTML trigger products snippet. This is pasted into the mailing or recommendation paragraph. For more information see below in "Integration in Mailing".

Product URLs
https://[customeraccount].peerius.com/tracker/er/link.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&triggerFireId={externaltriggerid}
https://[customeraccount].peerius.com/tracker/er/image.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&trigegrFireId={externaltriggerid}
https://[customeraccount].peerius.com/tracker/er/productinfo.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&triggerFireId={externaltriggerid}
Required fieldfunctions
{recipientid}
{externaltriggerid}
{externalproductid}
{externalusergroup}

How SMART Trigger works in connection REACH - Campaign

If Reach reacts on an event or rule and fires a trigger, they have to provide required information first that we need for the request of the recommendation images. This results in actually two API calls.

1.) https://api.campaign.episerver.net/http/form/AUTH_CODE_OF_RECIPIENT_LIST/updatefields?bmRecipientId=XXXXXXXXXXX&externaltriggerid=34wqer4421&externalproductid=prd-234451
2.) https://api.campaign.episerver.net/http/form/AUTH_CODE_OF_RECIPIENT_LIST/sendeventmail?bmRecipientId=XXXXXXXXXXX&bmMailingId=153340195500

With the first request we get the parameters the recommendation should be requested with. The bmRecipientId contains the email and identifies on Campaign side which user should get updated. The externaltriggerid contains the information for the recommendation widget which trigger fired to present the correct product recommendations.

Both parameters, bmRecipientId and externaltriggerid are mandatory. externalproductid and externalusergroup are optional and not every customer is using this.

Field function Third Party ID

To use the third party ID of a recipient in the content of a campaign mailing, the field function {bmThirdPartyId} can be used directly. Campaign will replace it with the Third Party ID associated with the recipient when rendering the email.

Configuration in Reach to use Third Party ID

The parameter bmThirdPartyId can be used in HTTP-API instead of bmRecipientId. It is supported on sendtransactionmail and sendeventmail and updatefields.

API-Calls look like this:

/sendtransactionmail?bmThirdPartyId=10034375000-af-1306-x&bmMailingId=XXXXX
/sendeventmail?bmThirdPartyId=10034375000-140601&bmMailingId=XXXXX
/updatefields?bmThirdPartyId=10034375000-140601&externaltriggerid=7897809134&externalproductid=prd-234451

Reach has a feature switch to enable usage of third party ids: Account → Site management → Products → Triggers → Hashed email addresses.

Notes

Please note that sendtransactionmail could be triggered even when there is no opt-in.

Following use case should ensure that the trigger is fired actually when the opt-in exists:

  • If customer makes opt-in about us he will have to enrich the data later -> only when the user has completed the opt-in the customer can add Third Party ID and only then the lookup works and the transaction mail goes out
  • When a user unsubscribes the transactionmail will not be send because we will block sending mails for users that are unsubscribed in a client. But this is only working when client is not configured with list-dependent unsubscribe!

 

Integration in Mailing

There are different snippets for triggermails with a dynamic number of products shown (like abandoned basket) and recommendations with a fixed number of products shown.

Recommendation URLs

A product link URL and image URL should look like this:

https://[customeraccount].peerius.com/tracker/er/link.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&date={dateFunction}
https://[customeraccount].peerius.com/tracker/er/image.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&date={dateFunction}
https://[customeraccount].peerius.com/tracker/er/productinfo.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&date={dateFunction}
 
triggerFireId may not be part of the URL, otherwise no recommendation is shown
 

Trigger mail URLs

https://[customeraccount].peerius.com/tracker/er/link.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&triggerFireId={externaltriggerid}
https://[customeraccount].peerius.com/tracker/er/image.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&triggerFireId={externaltriggerid}
https://[customeraccount].peerius.com/tracker/er/productinfo.page?e={recipientid}&site=[customer]t&rno=[0-n]&wid=[campaign]&triggerFireId={externaltriggerid}

Without a valid triggerFireId no products are shown.

For internal testing when developing templates please contact Michael Schindler to get a temporary wid (widget id) and choose a random numeric triggerFireId, which shows fallbacks. Please notify Michael after testing is done.

There a several ways to include the URLs in a mailing.

Using Source Code Paragraph or free text template

The integration of the REACH HTML snippet can be done via source code paragraph or free text templates. This is included in the standard pricing of the package.

Product Image formatting

The HTML snippets come without formatting, so the customer/supporter needs to add formatting to show images in the right size. This is why the recommendation paragraph is needed in the Episerver Template-Kit.

In a custom template the template should do the formatting.

Empty space for empty products

If there are more URLs set in the mailing than specified products returned by the REACH Widget the URLs return an transparent image 1px. Because of the formatting this might lead to empty boxes where a product should be.

This can be avoided by:

  • In REACH by customer: specifing same number of products and setting a fallback strategy for products in abandoned baskets (because number of products is specific per event.
  • In Campaign Mailing by customer: Choose a layout which positions the products vertically so it's just an empty 1x space.

Using Recommendations Paragraph in the Episerver Template - Kit

This is included in the standard pricing of the REACH package.

Alternatively it is possible to use the recommendation paragraph and manually copy the URLs for image, text and link into the paragraph form.

Using a Custom Template

In a Custom Template most often a source code paragraph is available but not very comfortable to use.

We mostly setup a new paragraph for those customers. Currently there is a best practice: The customers chooses one existing product layout for recommendations and maybe one other for trigger mails.

Testing trigger mails

Since a trigger widget usually only returns products if a certain recipient really created an action in the store there is a workaround:

  • REACH-AP: sets up a test widget with fallback product strategies
  • In Campaign: use this id and set an numerical value for externaltriggerid in the test list. Send test email.
  • Testing with fallback is possible for every recipient, If no Third Party ID is stored for a recipientid, then unknown (STRING) is returned and REACH returns a fallback product on test widgets.

 

FAQ

Can I use my Campaign Tracking with REACH?

Yes, these links will also be converted to tracking links.

Can I use my Third-Party-Tracking with REACH?

No, any parameters appended to the REACH urls will be cut off by Peerius and not forwarded to the customers site!

Can I use multiple list to send out trigger emails?

Yes, in every widget a different list can be specified, every such list must be appended with the fields above. Please note that using thirdPartyIds currently is only possible with Trigger lists using the same id field.