diff --git a/_docs/_partners/message_orchestration/channel_extensions/loyalty/punchh/code_generation.md b/_docs/_partners/message_orchestration/channel_extensions/loyalty/punchh/code_generation.md index 5abfd5e69ec..0676e39aaa3 100644 --- a/_docs/_partners/message_orchestration/channel_extensions/loyalty/punchh/code_generation.md +++ b/_docs/_partners/message_orchestration/channel_extensions/loyalty/punchh/code_generation.md @@ -7,7 +7,7 @@ page_type: partner search_tag: Partner --- -# Dynamic code generation +# Dynamic code generation with Punchh > A coupon code is a unique code that can be used by a single user (either single or multiple use). The Punchh framework generates coupon codes, which can be processed within a mobile app or at the point-of-sale (POS) system. @@ -16,16 +16,16 @@ Using the Punchh coupon framework and Braze, you can achieve the following scena - Generate a coupon code when the guest clicks a coupon generation link in an email: The coupon code will be generated dynamically and shown on a web page. - Generate a coupon code when the guest opens an email: The coupon code will be generated dynamically and shown as an image within the email. -## How to integrate Punchh dynamic coupon code generation +## Integrating dynamic coupon code generation -### Step 1: Create a coupon campaign in Punchh +### Step 1: Create a coupon campaign 1. Using a Punchh coupon campaign, create a dynamic generation coupon campaign as shown in the following image. 2. The Punchh coupon framework will generate the following parameters to enable dynamic coupon generation: - Dynamic coupon generation token: This is a system-generated security token for encryption. - Dynamic coupon generation URL: This URL will be embedded in the email as a link or image, as required by the business. -![The form for creating a coupon campagin in Punchh.][2]{: style="max-width:60%;"} +![The form for creating a coupon campagin in Punchh.]({% image_buster /assets/img/punchh/punchh8.png %}){: style="max-width:60%;"} ### Step 2: Generate signature and construct URL @@ -33,8 +33,8 @@ The JWT.IO library decodes, verifies, and generates JSON web tokens, an open, in The following `ClaimType` names can be used to ensure the uniqueness of guests and coupons: +- `campaign_id`: represents the system-generated Punchh campaign ID. - `email`: represents the user's email address. -- `campaign_id`: represents the system-generated Punchh campaign ID. - `first_name`: captures the user's first name. - `last_name`: captures the user's last name. @@ -42,100 +42,100 @@ To use the Punchh dynamic coupon code API, a JWT Token must be constructed. Add {% raw %} ```liquid -{% capture header %}{"alg":"HS256","typ":"JWT"}{% endcapture %} +{% assign header = '{"alg":"HS256","typ":"JWT"}' | base64_encode | replace: '=', '' | replace: '+', '-' | replace: '/', '_' %} -{% capture payload %}{"campaign_id":"CAMPAIGN_ID","email":"{{${email_address}}}","first_name":"{{${first_name}}}","last_name":"{{${last_name}}}"}{% endcapture %} +{% capture payload_raw %} -{% capture signature_structure %}{{header | base64_encode}}.{{payload | base64_encode | remove: '='}}{% endcapture %} +{ + "campaign_id": "CAMPAIGN_ID", + "email": "{{${email_address}}}", + "first_name": "{{${first_name}}}", + "last_name": "{{${last_name}}}" +} + +{% endcapture %} + +{% assign payload = payload_raw | replace: ' ', '' | replace: '\n', '' | base64_encode | replace: '=', '' | replace: '+', '-' | replace: '/', '_' %} + +{% assign unsigned_token = header | append: "." | append: payload %} {% assign secret = "DYNAMIC_COUPON_GENERATION_TOKEN" %} -{% assign final_signature = {{signature_structure | hmac_sha256_base64: secret}} %} +{% assign signature_raw = unsigned_token | hmac_sha256_base64: secret %} + +{% assign signature = signature_raw | replace: '=', '' | replace: '+', '-' | replace: '/', '_' %} -{% capture jwt %}{{signature_structure}}.{{final_signature | remove: '='}}{% endcapture %} +{% assign jwt = unsigned_token | append: "." | append: signature %} ``` {% endraw %} + Replace the following: | Placeholder | Description | |--------------------|------------------------------------------------------| -| `SERVER_NAME` | The name of your server. | | `DYNAMIC_COUPON_GENERATION_TOKEN` | Your dynamic coupon generation token. | | `CAMPAIGN_ID` | Your campaign ID. | ### Step 3: Append coupon code to message body -#### Link to Punchh web page +#### Linking to Punchh web page -To link to a Puncch-hosted web page, add the following snippet to your message body. +To link to a Puncch-hosted web page, add `{% raw %}{{jwt}}{% endraw %}` to the dynamic generation URL [you created earlier](#step-1-create-a-coupon-campaign-in-punchh). Your link should be similar to the following: {% raw %} -```liquid -https://SERVER_NAME.punchh.com/request_coupons/DYNAMIC_COUPON_GENERATION_TOKEN?sign={{jwt}} +``` +https://fakebrandz.punchh.com/request_coupons/7xY3bL9jRfZ1pA6mc8qD2eS4vT5wX?sign={{jwt}} ``` {% endraw %} -Replace the following: - -| Placeholder | Description | -|--------------------|------------------------------------------------------| -| `SERVER_NAME` | The name of your server. | -| `DYNAMIC_COUPON_GENERATION_TOKEN` | Your dynamic coupon generation token. | - When a user clicks the coupon URL, they'll be redirected to a Punchh-hosted web page, where their generated coupon will be displayed. -![Example confirmation message after a user successfully generates a coupon code.][1] +![Example confirmation message after a user successfully generates a coupon code.]({% image_buster /assets/img/punchh/punchh7.png %}) -#### Extract code via JSON as plain text +#### Extracting code via JSON as plain text -To return a JSON response, add `.json` before the sign query parameter of the Punchh URL as shown in the following snippet: +To return a JSON response, append `{% raw %}{{jwt}}{% endraw %}` to the dynamic generation URL [you created earlier](#step-1-create-a-coupon-campaign-in-punchh), then add `.json` after the token in the URL string. Your link should be similar to the following: {% raw %} ```liquid -https://SERVER_NAME.punchh.com/request_coupons/DYNAMIC_COUPON_GENERATION_TOKEN.json?sign={{jwt}} +https://fakebrandz.punchh.com/request_coupons/7xY3bL9jRfZ1pA6mc8qD2eS4vT5wX.json?sign={{jwt}} ``` {% endraw %} -Replace the following: - -| Placeholder | Description | -|--------------------|------------------------------------------------------| -| `SERVER_NAME` | The name of your server. | -| `DYNAMIC_COUPON_GENERATION_TOKEN` | Your dynamic coupon generation token. | - You could then leverage [Connected Content]({{site.baseurl}}/user_guide/personalization_and_dynamic_content/connected_content/making_an_api_call/) to insert the code as plain text into any message body. For example: {% raw %} ```liquid -{% connected_content https://SERVER_NAME.punchh.com/request_coupons/DYNAMIC_COUPON_GENERATION_TOKEN.json?sign={{jwt}} :save punchh_coupon %} +{% connected_content https://fakebrandz.punchh.com/request_coupons/7xY3bL9jRfZ1pA6mc8qD2eS4vT5wX.json?sign={{jwt}} :save punchh_coupon %} {{punchh_coupon.coupon}} -``` +```` {% endraw %} -#### Link image inside email content +#### Linking an image inside email content + +To link the coupon code inside an image: -To link the coupon code inside an image, add the following snippet to your message body: +1. Append `{% raw %}{{jwt}}{% endraw %}` to the dynamic generation URL [you created earlier](#step-1-create-a-coupon-campaign-in-punchh). +2. Add `.png` after the token in the URL string. +3. Embed your link in an HTML {% raw %}``{% endraw %} tag. +{% tabs local %} +{% tab example input %} {% raw %} ```liquid -` -``` + +```` {% endraw %} +{% endtab %} -Replace the following: +{% tab example output %} +![Rendered output of the coupon code image tag.]({% image_buster /assets/img/punchh/punchh9.png %}) +{% endtab %} +{% endtabs %} -| Placeholder | Description | -|--------------------|------------------------------------------------------| -| `SERVER_NAME` | The name of your server. | -| `DYNAMIC_COUPON_GENERATION_TOKEN` | Your dynamic coupon generation token. | - -Your output will be similar to the following: - -![Rendered output of the coupon code image tag.][3] - -## Associated error messages +## Error messages | Error code | Error message | Description | | --- | --- | --- | @@ -147,7 +147,3 @@ Your output will be similar to the following: | `usage_exceeded_by_guest` | This promo code has already been processed. | The usage of the code by a user exceeds the number of times a user can use it. For example, the dashboard configuration allows a single code to be used three times by a user. If it is used more than that, this error will occur. | | `already_used_by_other_guest` | This promo code has already been used by some other guest. | Another user has already used the code. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3} - -[1]: {% image_buster /assets/img/punchh/punchh7.png %} -[2]: {% image_buster /assets/img/punchh/punchh8.png %} -[3]: {% image_buster /assets/img/punchh/punchh9.png %} diff --git a/assets/img/punchh/punchh8.png b/assets/img/punchh/punchh8.png index cb7a0406d32..b6705f0e03a 100644 Binary files a/assets/img/punchh/punchh8.png and b/assets/img/punchh/punchh8.png differ