Source Link: https://help.lob.com/print-and-mail/designing-mail-creatives/maximizing-engagement/adding-qr-codes # Adding QR codes
## Overview
Lob’s platform allows you to generate a [QR code](https://www.qr-code-generator.com/qr-code-marketing/qr-codes-basics/) for each individual mailpiece you send. This feature is available via
* our [Campaigns tool](#lob-qr-codes-via-the-campaigns-tool) in the dashboard,
* our [APIs ](#lob-qr-codes-via-print-and-mail-api-and-campaigns-api)(Print & Mail and Campaigns API), and
* we also support the use of [3rd-party APIs or Javascript](#utilizing-qr-codes-outside-of-lob) to generate QR codes.
Personalized response tracking is a standard feature of digital marketing channels, but has traditionally been difficult to replicate in Direct Mail. However, with Lob’s QR code offering, personalized tracking can now be easily incorporated into your Direct Mail campaigns.
We offer [engagement analytics](#engagement-analytics-for-lob-qr-codes) to measure the impact of every mailpiece you send. This gives you the ability to track Direct Mail response data in real-time, long before any conversion event ultimately takes place.
## Lob QR codes via the Campaigns tool
{% embed url="https://lob.wistia.com/medias/xemj325aha" %}
How to add a QR code in Campaigns tool
{% endembed %}
### **Standard QR codes**
* All users can generate a single black and white QR code via the Campaigns tool in the dashboard for postcards, all letters, self-mailers, and snap packs.
* This QR code will be static, that is, a single URL will be applied across all recipients in a campaign.
* The QR code appears in the same location on each mail piece.
In Step 3 of Campaigns generation, after you’ve uploaded your creative (PDF or HTML), select "Add QR code" and a module will pop up.
In the top left-hand side of the QR code builder, under URL click the “Create QR Code URL” button to open an additional window. Enter the landing page URL; this will be used for all mailpieces (and all recipients) in a campaign. When you have input your URL, Save & Close to continue the QR code build.
Next, select “Generate QR code.” A QR code will appear on your mailpiece and you can adjust the size and the placement of the QR code. We recommend sizing no smaller than one inch for optimal readability, and your code should be placed inside the bleed lines, which you can toggle on and off.
When you are happy with your design, Save & Close.
### Custom QR codes
{% hint style="info" %}
These features are available for Enterprise users. Upgrade your [Print & Mail edition](https://dashboard.lob.com/#/settings/editions) to gain access to this feature, or reach out to our [sales team](https://www.lob.com/sales) to learn more.
{% endhint %}
**Custom QR code features are available for postcards, (standard) letters, and self-mailers only.**
With custom QR codes, you can customize the foreground and background color of the QR code, add a logo into the center of the QR code, and create personalized URLs with dynamic merge tags that are unique to each recipient.
#### Custom QR codes: Color
Match your design elements and branding by customizing the color of your QR codes.
In Step 3 of the Campaigns workflow, after you’ve uploaded your creative (PDF or HTML), open the QR code module by clicking the “Add a QR Code” button.
Within the customize section of the QR code builder, you will see an option to customize the Background color and Foreground color. The default color option is set to white and black respectively.
When selecting a color, you can pick from the color gradient selection, or if you have a specific hex color that your brand uses, you can type in or paste the hex value into the color picker to apply your changes. You can choose colors that align with your brand or design for your QR code, but ensure it remains scannable on mobile devices. We recommend using contrasting colors to maintain readability (for example, dark red on light grey has a better contrast than light grey on light blue).
When you are happy with your design, Save & Close.
#### Custom QR codes: Adding a logo
Further your brand by adding your company logo inside the QR code.
In Step 3 of the Campaigns workflow, after you’ve uploaded your creative (PDF or HTML), open the QR code module by clicking the “Add a QR Code” button.
Within the QR code builder, click the “Upload” button under Brand logo.
* Acceptable image types to upload and attach to your QR code are JPG and PNG and file size cannot exceed 1MB.
* When uploading a logo to your QR code, Lob will automatically resize the logo to fit the dimensions required for the QR code to properly display.
* For transparent images like PNG and SVG, Lob will automatically apply a background color behind the logo so that it’s readable. By default the background color is set to black. If you need a white background to show instead, reverse the colors in the QR code builder so that the background color is white and the foreground color is black as shown below.
When you are happy with your design, Save & Close.
We recommend you verify the QR code looks exactly like you want it to and scans correctly; you can view the Creative Proof to view a sample of a rendered mailpiece.
#### Custom QR codes: Personalized URLs
Build fully customizable and dynamic QR code URLs for a 1-1 recipient matching.
In Step 3 of the Campaigns workflow, after you’ve uploaded your creative (PDF or HTML),open the QR code module by clicking the “Add a QR Code” button.
In the top left-hand side of the QR code builder, under URL click the “Create QR Code URL” button to open an additional window to build out your customized URL. To add personalized merge tags into the URL for each recipient, click “Add merge tag” which displays fields for you to pull variables into your URL.
* For One-time campaigns, the merge tags will pull in the columns within the audience file added in Step 2 of the campaign builder.
* For Automated campaigns, the merge tags will pull fields from the integration and trigger components you’ve previously set up.
* When adding a merge tag into the URL, you can add a dynamic value as a key path in the URL e.g., _lob.com/\{{state\}}_ if certain recipients will receive a specific landing page for each state they reside in.
* If you want to add optional parameters to your URL, add a question mark “?” to the URL followed by the merge tag. Example: _lob.com/\{{state\}}/?\{{discount\_value\}}_ would output as _lob.com/california/?20_ to the end recipient.
* If you have a use case where you need the entire URL to pull from a row in your audience file that you have already created and included, you can simply add that URL as a merge tag, and only use that merge tag for the QR code URL: _\{{landing\_page\_URL\}}_
{% hint style="warning" %}
Ensure you use unique variable names in both HTML templates and QR codes. If you use the same variable names in both places, the previous mapping will be overridden, and your mailpiece will not generate correctly.
A merge tag can only be used once in a QR code URL. If you have already added a \{{state\}} merge tag to the URL, you cannot add it again.
{% endhint %}
**What if some recipients have an empty cell/value?**
If some recipients have empty merge tags, you can add an optional fallback for each merge tag. This fallback will only be used if the merge tag is empty. Adding a fallback is not required for the QR code to work properly.
For example, if a recipient’s \{{state\}} merge tag is empty, you can set a fallback to "California," and they will see "California" in the URL and still be directed to the correct page.
When you have input your URL, Save & Close to continue the QR code build.
## Lob QR codes via Print & Mail API and Campaigns API
### Standard QR codes
All users can generate standard QR Codes for postcards, all letters, self-mailers, and snap packs via API.
QR Codes are generated within the API call to create a Lob mailpiece. In addition to passing Lob the name, address, and creative you would like to send the recipient, you will also pass the required parameters to create a QR code: size, positioning, and the URL where you want to send the user upon a scan. Then, when Lob generates the mailpiece, Lob will also dynamically generate the unique QR code and incorporate it into your design.
Lob QR codes can be generated by including the [`qr_code` ](https://docs.lob.com/#tag/QR-Codes)object in the transactional API request body while creating [Letters](https://docs.lob.com/#tag/Letters/operation/letter_create), [Postcards](https://docs.lob.com/#tag/Postcards/operation/postcard_create), or [Self-mailers](https://docs.lob.com/#tag/Self-Mailers/operation/self_mailer_create). In the Campaigns API _(beta)_, this object can be found in the [Creatives (Create](https://docs.lob.com/#tag/Creatives)) call.
```javascript
"qr_code": {
"position": "relative",
"redirect_url": "https://www.lob.com/?customer_id12345",
"width": "2",
"top": "2.25",
"left": "3.125",
"pages": "back"
},
```
### **Custom QR codes**
{% hint style="info" %}
These features are available for Enterprise users. Upgrade your [Print & Mail edition](https://dashboard.lob.com/#/settings/editions) to gain access to this feature, or reach out to our [sales team](https://www.lob.com/sales) to learn more.
{% endhint %}
**Custom QR code features are available for postcards, (standard) letters, and self-mailers only.**
* **To add a logo** to the center of the QR code, include the `logo` key. Logos can be up to 2MB, but ideally should be optimized to a smaller file size.
* **To customize the colors:** An optional `style` object can be set on the `qr_code` request to customize the colors for the QR code. This enables users to fully select the colors that will be applied on the QR codes. The style object takes a `foreground_color` and a `background_color` option where you can provide the Hex code for the color you wish to apply to the QR codes.
* [See below](#customize-redirect-urls-for-postcard-letters-checks-self-mailer-api-endpoints) section on URL redirects for how to personalize URLs.
```javascript
// S"qr_code": {
"position": "relative",
"redirect_url": "https://www.lob.com/?customer_id12345",
"width": "2",
"top": "2.25",
"left": "3.125",
"style": {
"foreground_color": "#000000",
"background_color":"#ffffff",
},
"logo":{"url": "https://lob-assets.com/logos/lob_logo.png"},
```
### **Positioning**
Indicate the position of your QR code in your mailpiece by setting the required `Position` parameter to `relative`, then set the distance from a reference position of the “Bottom/Top” and “Right/Left” of your design, in inches. There are a total of 4 anchor combinations available for potential use: top-left, top-right, bottom-left, or bottom-right. Lob recommends using '**bottom-right**' as your placement anchor.
* Use `bottom` for your **vertical** parameter: The field takes in a value between 0 to max length of the creative
* Use `right` for your **horizontal** parameter: The field takes in a value between 0 to max width of a creative
### Pagination
An optional `Pages` parameter can be used to specify the pages, in a ‘comma separated’ format, where the QR code should appear. If not included, the default is page 1 for letters, or `front` for postcards.
* For **Postcards**, the values should be either `front`, `back`, or `front,back`.
* For **Letters**, the values can be specific page numbers or page number ranges (ex: `2,5` or `1-3`)
* For **Self-mailers & Snap packs**, the values should be `inside`, `outside,`or `inside,outside`.
{% hint style="warning" %}
- Currently, you cannot generate QR codes with different locations on different pages.
- Via API, users can add more than one QR code to a campaign mail piece (ex: front and back of a postcard, or front and back of a letter) **as long as it is placed in the exact location on each side**.
{% endhint %}
### Destination URL & redirects
Finally, you will set the **Destination URL** that the QR code resolves to by passing it into the `Redirect_URL` parameter. Since Lob QR codes are **dynamic**, you can pass a unique URL for every single mailpiece you create, such as to direct every mail recipient to a unique landing page, or to capture data using unique UTM parameters.
In the sample API request body above ("redirect\_url": "https://www.lob.com/?customer\_id12345") we are capturing the specific user ID of the intended recipient of the mailpiece in Lob’s website analytics when the QR code is scanned.
Every QR code generated will have a short Redirect URL assigned to it, which will resolve through to the Destination URL passed in the API call. This means you have the flexibility to change the Destination URL after the QR code has been generated, even if the mail has already been sent, as the initial Redirect URL will remain the same.
Once a QR code is scanned, the user will see a redirect screen (as shown on the right).
{% hint style="success" %}
All URLs passed in the `Redirect_URL` parameter should begin with “`http://`” or “`https://`”
{% endhint %}
#### Customize Redirect URLs for Postcard, Letters, Checks, Self mailer API endpoints:
To customize the `redirect_url` for each recipient, you will use `merge_variables`. In your `redirect_url` provide a template url, for eg: https://www.google.com?q=\{{name\}}, where the value for the \{{name\}} variable would come from the `merge_variables` section of the payload.
```javascript
{
“description”: “postcard with sample merge variables”,
"qr_code": {
"position": "relative",
"redirect_url": "https://www.lob.com/?{{customer_id}}",
"width": "2",
"top": "2.25",
"left": "3.125",
},
“merge_variables”: {
“customer_id”: “lob_12”
}
}
```
**Customize Redirect URLs in Campaigns API:**
With the Campaigns API _(beta)_, you have the option to set a single redirect for all recipients in your campaign or unique redirect URLs for each recipient.
**To set a single URL redirect for the entire campaign**, set the \`redirect\_url\` in the details section of the Creatives (Create) request to your desired URL to this field.
**Enterprise users can customize redirect URLs for each campaign recipient** by providing a URL template and a data mapping from the Audience file, enabling Lob to generate unique QR code destinations for each mailpiece.
* An example of a URL template for the r`edirect_url`, is [www.google.com?q=\{{name](http://www.google.com/?q=%7B%7Bname)\}}, you can add one or more variables in the template and submit the creative request.
* The next step is to let us know where this value comes from, and to do so we allow users to map `name` to any column from the Audience file. You can provide this mapping by sending a POST or a PATCH request to the /uploads endpoint for the campaigns.
* The `mergeVariableColumnMapping` holds the mapping for the `name` variable created in the URL template.
```javascript
{
"campaignId": "cmp_sample_id",
"requiredAddressColumnMapping": {
"name": "recipient_name",
"address_line1": "primary_line",
"address_city": "city",
"address_state": "state",
"address_zip": "zip_code"
},
"optionalAddressColumnMapping": {
"address_line2": "secondary_line",
"company": "company",
"address_country": "country,"
},
"mergeVariableColumnMapping": {
"name": "recipient_name"
}
}
```
### Errors
Lob API errors contain human-readable explanations in the `message` parameter.
For example, you may receive a `422` error containing the message “`qr_code.position is required`”. This indicates that no value was passed to the API in the `position` parameter.
## QR code best practices
{% hint style="success" %}
**Remember to test!** We recommend you verify the QR code looks exactly like you want it to and scans correctly.
* In the Campaigns tool you can view the Creative Proof to view a sample of a rendered mailpiece.
* If generating via API, use your Test API Key to preview your creative in Lob and verify that everything looks as intended.
{% endhint %}
* **Sizing:** All QR codes are square; the minimum width should be at least 1” so that the code can be easily scanned. In the API, set the size of your QR Code by passing through the `Width` parameter of your QR code in inches.
* **Mailpiece placement:** Lob QR codes will be pasted over your design like how Lob places the ‘[Address Block](../../artboard-layout#address-block-postage-8)’, so make sure to designate the size and positioning of your QR code _away_ from any critical designs.
* Do not place your QR code over the area in which the mailing address will be printed. [Reference the Ink-Free areas for each template here](https://help.lob.com/print-and-mail/designing-mail-creatives/mail-piece-design-specs/postcards-and-self-mailers).
* Make sure to leave 0.25” of space between your QR code position and any content of your mailpiece that you don’t want to be covered.
* When positioning your QR code, make sure to take into account the [bleed edge](../../artboard-layout#bleed-area-3) added to the artboard dimensions of the mailpiece. For example, the dimensions of a 4x6” Postcard in Lob are 4.25” x 6.25”.
* Lob QR Codes do not expire. If your destination URL expires, you may want to update live QR codes to redirect to an active landing page.
## Engagement analytics for Lob QR Codes
You can capture impact and engagement metrics from your mail sends with Lob QR codes in a few ways.
### Engagement analytics in the Lob dashboard
The [Mail Analytics](../../getting-data-and-results/mail-analytics) tab will display metrics for _all_ mail you have sent with Lob across any number of campaigns within a time period. QR code scan data can be found under the Engagement tab.
From the Campaigns dashboard, when you drill down to the detail/status page for any individual campaign you can view [_campaign-specific_ analytics](../../../send-mail/launch-your-first-campaign#campaign-analytics). QR code scan data can be found under the Analytics tab > QR Code Engagement.
### QR Code Analytics endpoint
Retrieve analytics for Lob-native QR codes from Lob’s `qr-code-service.lob.com` API endpoint. For detailed data, see the QR Code section in our [API documentation](https://docs.lob.com/#tag/QR-Codes).
{% hint style="warning" %}
QR Code scan data is deleted after 90 days.
{% endhint %}
### Real-time notifications via webhooks
Whenever a QR code is scanned from a mailpiece, there will be an event generated, such as `postcard.viewed` or `letter.viewed`. You can enable notifications on these events by setting up webhooks that will alert you when the scans occur.
This can be incorporated into your omnichannel marketing campaign to subsequently trigger an email, mailpiece, or other action when a mailpiece is viewed.
{% hint style="info" %}
See the webhooks section in our [API documentation](https://docs.lob.com/#tag/Webhooks), or learn more about [using webhooks](../../getting-data-and-results/using-webhooks) here in the help center.
{% endhint %}
### UTM parameters
[UTM parameters](https://en.wikipedia.org/wiki/UTM_parameters) are short text codes that you add to URLs (or links) that help track performance. Because QR codes can be generated dynamically at the time of their creation, we can generate QR codes with UTM parameters that correlate to the recipient.
For instance, if we are sending a mailpiece to a recognized user we’ve assigned a Customer ID of “`12345`”, we can append that ID to their Destination Page URL, so that the user can be recognized by our web analytics once they reach the page: `www.lob-example.com/login?customer_id=12345`. This enables you to more easily attribute customer activity back to this mailpiece.
UTM parameters can also be used to track Campaign responses, A/B test variants, and other key data points that inform your understanding of the response to your campaign.
