You'll need to create your Template for displaying a recommendation before you can add the URLs!
1. Copy the Item URLs
Once you have the screenshot template for your individual items created, your screen will update to display the "Use Template" information. Copy the code within the box - these are the URLs you'll need to embed in your email in each space where you want an item to be shown. The first URL will look up the link for the item that is being displayed. The second URL will look up the image that we have dynamically generated for that item.
2. Ensure URLs can be personalized by your email system
Each URL has three parameters that will need to be updated slightly in order to be personalized:
- <newsletterId> - you can use any value here as long as it is unique to the email campaign you are sending. If your email system already uses an ID to identify campaigns you can use that, or you can make up a name for it. Your "Summer Sale: 50% off Storewide!" campaign might be called "2018-Summer-Sale-50" as the newsletterId.
- <userId> - this is the ID of the user you are sending to as they are known to LiftIgniter (we use this to personalize based on that user's behavior history). If you have an API integration, you are probably already sending user's activity data to us with a known ID value. If you are using a Javascript integration, you can extract the ID we assign them in the LiftIgniter "_ig" cookie and collect it as part of your newsletter signup, login, or other email collection process.
- <slot> - the number of the placement each item is assigned to. If you want to show 6 items as recommendations, each pair of links should be numbered 1 through 6. In most cases, these are the only parameters you'll need to modify manually.
Most email platforms have the ability to "personalize" the content of the email. Typically, this means using placeholders like {{First Name}} in the text of your email. Most also allow the same to be done in URLs, personalizing query string variables or URL paths.
Here are a pair of URLs with the IDs filled out as personalization variables. Note that the slot number has been hard-coded as a "1" - this tells us that the highest ranked item will be displayed there.
<a href="https://api.petametrics.com/v1/email/link/{{newsletterId}}/demo-template/1?jsk=f7tsbsle43k5irci&userId={{userId}}">
<img src="https://api.petametrics.com/v1/email/image/{{newsletterId}}/demo-template/1?jsk=f7tsbsle43k5irci&userId={{userId}}&storeRecs=false" />
</a>You can also add any additional parameters that you want into the href link. Any url parameters included with the href other than jsk, userId, and uid will automatically "pass through" as url parameters on the page on your website that LiftIgniter sends the user to. For instance, if you want to pass in a key-value pair called blastName=morning, you can edit the href as follows; note that you should not add these pass-through parameters to the img src value:
<a href="https://api.petametrics.com/v1/email/link/{{newsletterId}}/demo-template/1?jsk=f7tsbsle43k5irci&userId={{userId}}&blastName=morning">
<img src="https://api.petametrics.com/v1/email/image/{{newsletterId}}/demo-template/1?jsk=f7tsbsle43k5irci&userId={{userId}}&storeRecs=false" />
</a>Although the example above used a fixed key-value pair, you can also add url parameters where the key-value pair varies by user. The controlling logic for how to vary the parameters must be managed through your email system.
3. Add all URLs to your email template
We'll use a very simplified example layout to demonstrate. Let's say you want to have 6 items displayed in a single recommendation area in your email. The HTML for that might look like this:
<table style="width:100%"> <tr> <td>Item 1</td> <td>Item 2</td> <td>Item 3</td> </tr> <tr> <td>Item 4</td> <td>Item 5</td> <td>Item 6</td> </tr> </table>
Now we'll fill in each Item with the URLs. Note that the <slot> number for each pair of URLs in a <td> row is the same - if there is a mismatch between slot numbers in a pair of URLs, the destination URL won't match the item shown for that recommendation!
<table style="width:100%">
<tr>
<td>
<a href="https://api.petametrics.com/v1/email/link/{{newsletterId}}/demo-template/1?jsk=f7tsbsle43k5irci&userId={{userId}}">
<img src="https://api.petametrics.com/v1/email/image/{{newsletterId}}/demo-template/1?jsk=f7tsbsle43k5irci&userId={{userId}}&storeRecs=false" />
</a>
</td>
<td>
<a href="https://api.petametrics.com/v1/email/link/{{newsletterId}}/demo-template/2?jsk=f7tsbsle43k5irci&userId={{userId}}">
<img src="https://api.petametrics.com/v1/email/image/{{newsletterId}}/demo-template/2?jsk=f7tsbsle43k5irci&userId={{userId}}&storeRecs=false" />
</a>
</td>
<td>
<a href="https://api.petametrics.com/v1/email/link/{{newsletterId}}/demo-template/3?jsk=f7tsbsle43k5irci&userId={{userId}}">
<img src="https://api.petametrics.com/v1/email/image/{{newsletterId}}/demo-template/3?jsk=f7tsbsle43k5irci&userId={{userId}}&storeRecs=false" />
</a>
</td>
</tr>
<tr>
<td>
<a href="https://api.petametrics.com/v1/email/link/{{newsletterId}}/demo-template/4?jsk=f7tsbsle43k5irci&userId={{userId}}">
<img src="https://api.petametrics.com/v1/email/image/{{newsletterId}}/demo-template/4?jsk=f7tsbsle43k5irci&userId={{userId}}&storeRecs=false" />
</a>
</td>
<td>
<a href="https://api.petametrics.com/v1/email/link/{{newsletterId}}/demo-template/5?jsk=f7tsbsle43k5irci&userId={{userId}}">
<img src="https://api.petametrics.com/v1/email/image/{{newsletterId}}/demo-template/5?jsk=f7tsbsle43k5irci&userId={{userId}}&storeRecs=false" />
</a>
</td>
<td>
<a href="https://api.petametrics.com/v1/email/link/{{newsletterId}}/demo-template/6?jsk=f7tsbsle43k5irci&userId={{userId}}">
<img src="https://api.petametrics.com/v1/email/image/{{newsletterId}}/demo-template/6?jsk=f7tsbsle43k5irci&userId={{userId}}&storeRecs=false" />
</a>
</td>
</tr>
</table>Now when you send your campaign, your email platform should fill in the necessary IDs for personalizing the email. Make sure to test that you have the right placeholders in the ID portions of the URL for your system to fill them out correctly!
What If Someone Has No UserID?
If you don't have a userId for someone, that's okay. You could leave it blank in the URL, in which case we'll return a set of generalized recommendations (usually what's most popular on the site right now). However, we generally recommend assigning them a random ID and we'll use their email behavior to start personalizing for them in the future - we'll keep track of what we've recommended for them in previous emails, and what they've clicked on and use those as factors in our future email recommendations for that user.