Refer a Friend

You're currently viewing XMPL V3

Attention: XMPL V5 beta is now available!

XMPL provides the ability to extend your recipient base by creating pages that allow an existing recipient to recommend the company, site or product to a friend.

You do this by creating a "refer" form in a webpage. The refer form functionality is similar to the update and registration forms, however instead of the current recipient's fields the target referred recipient fields are edited, and once the form is submitted the referred recipient is added. Once the form is submitted and the referred recipient is added to the database, the page may redirect to another page, possibly thanking the recipient for recommending the site to the referred person, or stay in the same page, for transitioning to a thank you text and/or recommending the site to another person.

XMPL isolates the recipient data from the referred recipient data, so you can use both in the same page. Using the fields of the referred recipient, for both the initial addition stage, and the later thank-you-for-reference stage is very similar to using the regular recipient fields, including the ability to use all types of ADORs.

The following section discusses the creation of "refer" forms and what can be done with them.
To see an example of a refer form, refer to the SDK "refer.html".

Set Up a Refer Form

To add a refer form to your page use a plain HTML form and add to it the xmp-refer attribute. In it include input fields with xmp-write-ador reference. The following is an example of a simple refer form:

<form xmp-refer
      xmp-success-url="referThankYou.html">
    <ul>
        <li>
	    First Name : <input type="text" 
                                xmp-write-ador="xmp.referredRecipient['First Name']"  
                                size="30">
        </li>
        <li>
	    Last Name : <input type="text" 
                                xmp-write-ador="xmp.referredRecipient['Last Name']"  
                                size="30">
        </li>
    </ul>	        		
    <input type="submit" value="save">
</form>				

The form tag contains the following attributes:

1. xmp-refer - marks this form as a refer form. When submitted, the values in the form together with their respective ADOR references are collected and a new referred recipient is created.
2. xmp-success-url - similarly to other forms, the xmp-success-url attribute can be used to define a redirection URL once the form is submitted. This attribute is optional.

All other attributes that are common for XMPL forms are available here. You can find explanations about them in the the following page: Update Recipient Data.

Similarly to other forms, the association between ADORs and form fields is carried out using xmp-write-ador, however there is a critical difference. The reference to a referred recipient uses xmp.referredRecipient[XXXXX] instead of xmp.r[XXXXX]. This is because we want to affect the referred recipient data, and not the viewing recipient data. This isolation allows us to use both entities in the same page, as we will see later when defining reference thank you pages.
Other than this, ADOR usage is the same. The name of the ADOR should be provided, and it should refer to a write ADOR in the plan.

Post Submit Behavior

Once the form is submitted, using a plain submit button, the XMPL infrastructure sends a recipient addition request to the XMPL server. It is very similar to how registration works, however data that is retrieved from the registration addition request about the referred recipient is saved in xmp.referredRecipient. In addition, the referred recipient ID is saved in xmp.referredID (as opposed to the recipient ID which is stored in xmp.recipientID).

At this point you can either choose to stay in the same page, transitioning to a "thank you" phase and/or allow to refer another recipient, or just navigate to another personalized or non-personalized page.

Redirecting to a Thank You Page

When navigating to another page after submitting the form, the referred recipient ID is saved in a cookie and transferred to the next page. This means that if the next page contains any references to the referred recipient ADORs, they will be loaded with data once the page loads, in a similar manner to how the recipient data is loaded in a personalized page.

This allows you to create a thank you page. You can see an example in referThankYou.html.

The following is an extract from this page. It is important to note that this page is redirected from the refer.html page and does not contain any form whatsoever:

<div class="section-title">
  Thanks {{xmp.r['First Name']}}. 
  We will be with {{xmp.referredRecipient['First Name']}} {{xmp.referredRecipient['Last Name']}} soon.
  <br>
  <a href="index.html">back home</a>
</div>

Note how both entities are used in the same page - the xmp.r entity is used for its First Name ADOR, and the xmp.referredRecipient entity is used for its First Name and Last Name ADORs. This works because when the XMPL (specifically, the XMPPersonalizedPage controller) scans the page for ADOR references of either of the entities, and based on the cookies-provided data of recipient and referred recipient IDs retrieves it from the server.

Transitioning to "Thank You" in the Same Page

You can choose to stay in the same page by not providing the xmp-success-url. If you want to transition the page to a stage that is aware of the referred recipient data after the form has been submitted, use a similar method to the one used in registration, described here.

To stay on the page after the form was submitted and show/hide relevant sections upon successful submission use the ng-show attribute with a condition on the xmp.referredID. The referred recipient ID becomes available only after submit, and therefore can control the different areas visibility.

Reusing the Referred Recipient Form

The xmp.referredRecipient entity in a referred recipient form is isolated from the same entity outside of the form. The former is used in the form itself to control the user interaction. The external entity is based on the data that is retrieved after submitting the form.

This particular feature of the refer form allows you to reuse the refer form. If you want to allow the user to add another recipient after submitting the form, simply avoid redirecting. The user can now type in the form another referred recipient data. Outside of the form any references to the referred recipient are controlled by the data that was retrieved for the last referred recipient, so there is no problem in both thanking the recipient for the latest referral and having them type in data for another reference.

Adding the ReferrerID

Commonly one wants to include the referrer ID in the record of the recipients being referred. The solution requires adding a column in the database, an ADOR, a hidden field in the submitted form, and a special Angular directive that will push the submitter RecipientID into the field.

<body ng-app="xmp.app" 
      ng-controller="XMPPersonalizedPage" 
      xmp-cloak 
      xmp-tracking-page-name="Landing">
	  <script>
                //The function "angularComponentsOnReady"  is required 
               //from xmp.min.js version 1.9.1 and above
              var angularComponentsOnReady = function() 
              {
		angular.module('xmp.app').directive('referrerId', function() {
			function link(scope, element, attrs) {
					scope.xmpReady(function () {
						scope.xmp.referredRecipient.ReferedByID = scope.xmp.recipientID;
					});
			};

			return {
				link: link,
				restrict: 'A'
			};
		}); //directive
	    } //end angularComponentsOnReady 
         </script>
	  
	Your name: {{xmp.r.Fname}}<br/>
	Referrer ID: {{xmp.r.ReferedByID}}<br/>
	<br/>
	Refer a recipient <br/>
    <form xmp-refer>
        First Name: <input type="text" xmp-write-ador="xmp.referredRecipient.Fname">
        <input hidden referrer-id type="text" xmp-write-ador="xmp.referredRecipient.ReferedByID">
        <input class="btn-primary" type="submit" value="save" xmp-success-js="alert('added')">
    </form> 
</body>

Using in an Anonymous Page

Although most of the time you would use a refer form in a personalized page (using an ng-controller attribute with XMPPersonalizedPage value), you can definitely use it also in an anonymous page (using XMPAnonymousPage value). The usage method is identical.

Next

Another method of adding more people into your campaign is by the means of social media. To learn how to add social media sharing to your webpage with XMPL, refer to Social Media Tags.