SmartLink Basics
What is a SmartLink?
“SmartLinks” are an essential part of distributing wallet passes to your users. These URLs are device-aware, meaning when they are clicked on, the URL determines the device’s OS and prompts the user to add the corresponding wallet pass to their device. In addition, these URLs can carry information specific to the pass holder and then auto-populate that content into any tokens on the mobile wallet pass.
What Makes Up a SmartLink?
Before we teach you how to retrieve and deliver your SmartLink, let’s break down the components of one. Our basic SmartLink URLs can be boiled down into 4 main components:
- Vibes platform URL
- Campaign token
- UUID
- Tokens
These values are generally placed in the following order to make up the SmartLink URL:
(Vibes Platform URL)(Campaign Token)(UUID)(Tokens)
For example:
https://mp.vibescm.com/c/Campaign_Token/UUID?data[Token_Name_1]=Token_Value_1&data[Token_Name_2]=Token_Value_2
Learn more about each of these components, as well as some best practices in the sections below:
Vibes Platform URL
Let's start with the platform URL. You will be using the following value for all your SmartLinks:
https://mp.vibescm.com/c/
See below the value in an example URL
Mobile vs. desktop
Take note that SmartLinks have "/c/" after the platform URL. When a SmartLink is clicked on from a desktop browser instead of a mobile device and you have set up a mobile page fallback for your campaign, the resulting URL structure will change to have “/p/” in place of “/c/”. When testing, sometimes the fallback page can be shared with stakeholders and other testers instead of the actual SmartLink - you can check on that by looking at the value just after the platform URL.
Campaign token
Next, we have the campaign token. This is a value unique to each campaign, so it indicates which pass template should be downloaded.
You can find the token for each of your campaigns in the Wallet Manager tab of the platform. Navigate to the wallet campaign in question and locate the six-digit number at the very end of the SmartLink.
In your link, the campaign token comes directly after the platform URL:
UUID
The UUID is the value we use to determine who the wallet pass is being distributed to. It is a string of characters that is unique to each individual, allowing them to be identified.
When sending a SmartLink, you can set the UUID to any unique value that you’d like to use to identify your end users. For example, you can use email address, loyalty_id, offer code, or any other unique value.
If you’re sending a mobile message from the Vibes platform, this value will automatically be populated for each recipient. However, if you’re sending the SmartLinks from an email or other channel, you’ll need to manually populate the UUID yourself. For more information on available UUIDs, check out our Person API documentation.
Where the UUID appears in the URL may vary. Below is three possible methods and examples of each:
Method 1
The most common method is to add the UUID directly after the campaign token as a value without the field name or any other prefix.
Example:
Method 2
Another method is by using "unique_identifier"="example_uuid_value" after the question mark along with the other tokens.
Example:
Method 3
A third option is to use the sample placing as in method 2, but to use "uuid"="example_uuid_value" as the identifier.
Examples:
Tokens
Wallet tokens are variables used to populate your pass template. There are two types of tokens:
- Standard tag variables: These tokens are static values that you define in the SmartLink and will populate in the pass. The data for standard tags is populated directly in the SmartLink.
- Custom field variables: The tokens are dynamic based on the values in the customer’s person record. For example, you can use a custom field to populate a person’s first name onto their wallet pass.
Standard tag variables
Standard tag variables are used to transmit data via a SmartLink.
For example, say you’d like to distribute a wallet pass to a user via SMS. Just for downloading the pass, you’d like to give them 700 loyalty points. You’ve already set up your wallet templates to include a place where this value can display, like in the below screenshot.
Therefore, if we’d like to update that value to 700, our SmartLink might read as follows:
Note that the tag name in the URL must match the variable name in the pass template exactly. These do not need to be added as custom fields in the platform. These values can be changed after the pass has been added by using a batch file update, API call, or by having the user click on another SmartLink with the same campaign token with new token values.
Formatting tip
To include data in your URL that has spaces, abide by URL encoding standards. For example, in the URL below, notice that the value being used for the reward_name field includes "%20" instead of an actual space.
There are a number of free tools that can help you test your formatting.
Custom field variables
Custom field variables are variables that are pulled from a user’s person record either in the mobile database or in a recipient list. In these tokens, you won’t define the exact value; instead, you’ll direct the template to pull the data from the user’s associated person record or uploaded data.
Using mobile database fields
For example, say you’d like to personalize your mobile passes by including a customer’s first name, and that you have already collected this information and stored it on their person record. Because this value lives in the Mobile Database, you do not need to include it in your SmartLink. Instead, when you set up the variable on your template, you’ll use mdb. in front of the field name. Using the unique identifier in the SmartLink, the template will identify the user and populate the data stored in the mobile database.
Updating custom fields on wallet passes
Custom fields are static, not dynamic. If you update the field in the Vibes person record, the wallet pass will not automatically update to reflect the new information. To update a wallet pass, use the Update a wallet item method or import new data via a wallet batch update.
See the example screenshot below:
Using recipient lists
If you are distributing the wallet passes through a broadcast in the Vibes platform, an alternative option for custom fields would be putting the data right into the recipient list being used as either a broadcast trigger or as a filter in the Narrow By field.
When you set up your wallet template, you can add fields from a recipient list using the variable {{ rl.column_name }}. For example, if you have a column called first_name, the tag would be {{ rl.first_name }} .
SmartLink Security
Any SmartLink distributed out of the Vibes platform is a secure and does not require any additional encoding.
JWT is a JSON-based open standard for encoding and/or signing web tokens that assert some number of claims. For example, a server could generate a token that has the claim "logged in as admin" and provide that to a client. The client could then use that token to prove that it is logged in as an admin.
The tokens are signed asymmetrically using a private/public key pair, or symmetrically using a shared_key. JWT claims can be used to pass the identity of authenticated users between an identity provider and a service provider, or any other type of claims as required by business processes.
The below is intended to help you implement the JWT protocol with Wallet Manager SmartLinks. SmartLinks are a Platform URL where you can send any and all traffic, and the network filters the different traffic segments to the corresponding offers and valid offers (in Vibes’ case, to a Wallet pass).
Wallet Manager SmartLinks support JWT protocol for encoding and signing all URL parameters through any channel. This ensures that all URL parameters being passed in on the Wallet SmartLink can be checked and ensured as accurate.
Supported Algorithms:
- RS256 with asymmetric signing that utilizes
private_keyfor signing andpublic_keyfor signature validation. This is Vibes' preferred JWT encoding algorithm. - HS256 with symmetric signing that utilizes a secret key shared between multiple parties. This should be used only when required by a third-party distribution channel.
RS256 Algorithm:
- Private keys are not to be shared with Vibes. Private keys are used by the distribution channel (email, mobile ad, webform, and so on) to encode and sign the JWT value.
- Public keys will be shared with Vibes to verify the signature and encoded data.
HS256 Algorithm:
- Secret keys are used by the distribution channel (email, mobile ad, webform, and so on) to encode and sign the JWT value and shared with Vibes to verify the signature and encoded data.
Headers
"headers": {
"alg": "RS256",
"aud": "123456", /* Optional Header: Smartlink Token used to verify campaign. If mismatched, JWT is not used */
},
Syntax for URL parameters
{
"unique_identifier": "4710104481809485710", /*unique_identifier value or uuid is required for JWT*/
"data": {
"first_name": "Joane" ,
"last_name": "Smith",
"code": "4285720"
}
}
Example Wallet Manager SmartLink with JWT
The following shows an example SmartLink using any JWT generator with RS256 algorithm to sign all the URL parameters for a given SmartLink recipient.
- URL parameters to encode and sign: unique_identifier=81809485710&data[first_name]=joane&data[last_name]=smight&data[code]=42857201
- Sample JWT generated for the above URL parameters:
9urfmvguue45afea9r3t.r4lfupfzvk4yxmxwfbah.9tjdjslh4kofa0e6rtll
The following is an example of a JWT encoded and signed SmartLink
Example Wallet Manager SmartLink without JWT
The following shows SmartLink URL examples that are not using JWT.
- SmartLink base URL: https://mp.vibescm.com/c/<smartlink_token>.
- SmartLink with URL Parameters: All data from any source used to personalize and identify SmartLinks are passed in as URL parameters onto the SmartLink. This included the Wallet Manager unique_identifer:
What's Next?
Learn how to deliver a Smartlink with our delivering a SmartLink guide.
Updated 6 months ago