Support Documents
Submit a Ticket

Zinrelo Integration in a Mobile app

Learn how to integrate the Zinrelo functionality in mobile apps.

Suggest Edits

Purpose

The purpose of this document is to help client developers integrate the Zinrelo functionality in mobile apps. This document will enlist the integration details and also provide information about the API endpoints required to address various use cases.

Integration

Zinrelo has a comprehensive suite of APIs for various purposes - awarding points, redeeming points, fetching transactions, fetching user information etc. Using these APIs, businesses can build their own version of the loyalty end user dashboard. However, the end user dashboard also contains various elements and functionalities, which cannot be mimicked using the APIs. In order to save developers' time and effort of building the end user dashboard from scratch, Zinrelo recommends a hybrid approach for integration.

The hybrid approach involves using the out-of-box end user dashboard that Zinrelo provides along with different API endpoints that you’d have to implement at various touch points in the app. The out-of-the-box dashboard can be chosen from one of the 4 themes that Zinrelo offers. You will be able to change the colors and text in this out-of-the-box dashboard from the Zinrelo admin console. Advanced customization is also possible using CSS. The dashboard ensures that the end user experience is uniform across mobile web, mobile app and desktop web.

The hybrid approach of integrating Zinrelo in the mobile app has been broken down into the following steps:

Step 1: Implementing the Create User API:
This is required to create a loyalty member in the loyalty program.

Step 2: Implementing JavaScript authentication to embed the Zinrelo End User Dashboard in a webview:
This is required to render the out-of-the-box dashboard in a mobile webview in the mobile app

Step 3: Implementing the Purchase Tracking API
This is required to track purchase-like activities and award points.

Step 4: Implementing ‘Award’ API
This is required to track non-purchase activities

Step 5: Implementing ‘Get User’ API
This is required to fetch and display user information at different places in the app other than the out-of-the-box end user dashboard

Implementing the Create User API

You may choose to auto-enroll members in the loyalty program or you may have an explicit enroll. In either of the cases, whenever you wish to create a loyalty member in Zinrelo, you can use the Create User API.

Details of the API: https://help.zinrelo.com/reference/create-a-loyalty-member
Authentication details:https://help.zinrelo.com/reference/authentication
API Endpoint:
POST https://api.zinrelo.com/v1/loyalty/users
Parameters:
first_name: First Name of the loyalty member
last_name: Last Name of the loyalty member
email: Email address of the loyalty member
uid: Unique ID of the loyalty member

Implementing javascript authentication to embed the Zinrelo end user dashboard in a webview:

The JavaScript authentication is required in order to render the out-of-the-box Zinrelo end user dashboard.

In your app navigation panel-

  1. Introduce a CTA. E.g: “Rewards Program” or “Medocity Rewards” or “Loyalty Points” or “Points Dashboard”

Integration in a Mobile app

*For e.g: The Dashboard CTA in the image on the left leads to a page that opens up a webview.

  1. This CTA should open a page that is implemented as a Webview.

a. It is recommended that instead of simply loading the html in a webview, this page be hosted at a URL and this page can then be opened in the webview.
b. Here is a sample of a hosted page that accepts the attributes that have to be passed to Zinrelo in the URL parameters and loads the page in the webview- [<https://zrlprodconfmobile.s3.amazonaws.com/mobiledashboard.html>]

  1. On this page, you will need to implement the following javascript - 
<script type="text/javascript">
 
 window._zrl = window._zrl || [];
 
 var init_data = {
    'partner_id' : <Partner- ID>,
    'email' : <Email address of the loyalty member>,
    'name' : <User Name>,
    'user_id' : <Unique-user-ID>,
    'ts' : <Current TimeStamp in epoch format>,
    'access_token' : <SHA256 hash of the string formed by concatenating - user_id, email,partner_id, api_key and ts - in the same order as mentioned >
  };

 _zrl.push( [ 'init' , init_data ] );

</script>

<script src="//cdn.zinrelo.com/js/all.js" type="text/javascript"></script>
  1. The important part here is the accesstoken - This needs to be generated by concatenating the _user_id, email,partner_id, api_key and ts in the exact same order and then taking a SHA256 hash of the formed string. The API key for your account can be found in General >> API Keys. And from here, you can select the API key you created for this purpose.
    Please note: The API Keys section under General is only visible to admins with full access.

For instructions on generating API keys, please refer to this document.

The JavaScript authentication is also elaborated at https://help.zinrelo.com/docs/basic-integration-and-authentication

  1. On the same page, place the following div with the width as 100% and height a minimum of 625px.
<div id='zrl_embed_div'></div>
  1. Note down the URL of this page. You will need to set an identifier for this URL in the End User Dashboard configuration in Zinrelo Admin Console. Please consult Zinrelo Support if you have any questions.

Integration in a Mobile app

  1. That’s it! The Zinrelo end user dashboard will start rendering in the mobile app in this webview. For any cosmetic changes to the dashboard, please reach out to Zinrelo support.

Implementing the Purchase Tracking API

A loyalty program should be configured to award points for a number of activities. The most popular and obvious one of these activities is the ‘Purchase’ activity. If purchase of a product or services is one of the activities in your mobile app/ web platform that you wish to award points to the users for, the Purchase Tracking API endpoint lets you send the required information to Zinrelo, so that Zinrelo can process the points.

Prerequisite: The Purchase activity should be enabled in the Zinrelo admin console and set to active.
Details of the API: https://help.zinrelo.com/reference/award-points
Authentication details: https://help.zinrelo.com/reference/authentication
API Endpoint:
POST https://help.zinrelo.com/reference/award-points
Parameters:
The detailed information about the parameters for this API endpoint is elaborated at https://help.zinrelo.com/reference/award-points

The product information sent in this API will be used to further process rules on different product categories, product IDs, etc.

This API endpoint should be called after confirmation of the purchase.

Implementing ‘Award’ API

As mentioned above, a loyalty program may have other non-purchase activities like “becoming an email subscriber”, “writing a review”, “completing a survey” that you may want to award points for. For this purpose, Zinrelo has an Award API endpoint, which you can use to award points for these activities upon the activity completion.

Prerequisite: The activity for which you will be making this API call should be configured in the Zinrelo Admin console and set to active. You will need the activity ID of this activity to pass in the API call.
Details of the API: https://help.zinrelo.com/reference/award-points
Authentication details: https://help.zinrelo.com/reference/authentication
API Endpoint:
POST https://help.zinrelo.com/reference/award-points
Parameters:
The detailed information about the parameters for this API endpoint is elaborated at https://help.zinrelo.com/reference/award-points

Implementing ‘Get User’ API

At different touch points in the app, you may want to either show the tier information or their available points or you may simply want to have a business logic around user attributes like tier, tag, available points, etc. For these cases, you can use the Get User API call to get the latest member information.

Details of the API: https://help.zinrelo.com/reference/retrieve-a-loyalty-member-with-member-id
Authentication details: https://help.zinrelo.com/reference/authentication[https://help.zinrelo.com/reference/authentication
API Endpoint:
GET https://api.zinrelo.com/v1/loyalty/users/{user_email}
API Response:
The detailed information about the API response is elaborated at https://help.zinrelo.com/reference/retrieve-a-loyalty-member-with-member-id

Updated 6 months ago