Getting started with Mapp Connect and a custom plugin

Prerequisites

General

• Technical knowledge of API and JSON is required

• You should be familiar with the following features of Mapp Engage:

  • Groups

  • Audience

  • Related Data

  • eCommerce

Requirements for your app

• To build your plugin, you can use our PHP, node.js client, or Java SDK (.jar file).

• Your application needs to handle authentication for Mapp Connect. It's recommended that your app has the UI for providing the Integrations ID, Secret Key, and API address for authentications. However, those values can also be hard-coded in the client file. 

• Use the GET API to obtain the Groups and Prepared Messages from your Engage instance into your app. This allows you to add contacts with/without attributes to groups and send messages (Email, SMS, In-App, Push).

Packages and Downloads

GitHub Repositories

• PHP

• Java

• JavaScript (node.js)

Postman Sandbox

This Postman collection can be used to test how to authenticate and use all types of events. To use it, create a free Postman account (or download the free app) and upload the collection. The procedures described below use this collection to demonstrate how it works.

DOWNLOAD THE POSTMAN SANDBOX COLLECTION

Procedures

These procedures use the demo Postman collection (above) to demonstrate the authorization and API testing process. Similarly, you can authorize and test your app for use with Mapp Connect.

To perform these procedures, you need to create a Postman account and upload the collection in the Collections section of your Postman workspace.

Test authentication

1. Replace the API URL in the URL line with the API URL of the cluster where your Engage system is located. In our example, the part that needs to be replaced is "jamie.h.shortest-route.com/charon/api/v1/". If you don't know which cluster applies to your system, contact your account or customer success manager.

   Available clusters

   • EU L3 cluster: https://jamie.g.shortest-route.com/charon/api/v1/ 

   • US L3 cluster: https://jamie.a.shortest-route.com/charon/api/v1/

   • EMC cluster: https://jamie.h.shortest-route.com/charon/api/v1/ 

   • EMC-US cluster: https://jamie.c.shortest-route.com/charon/api/v1/ 

   Please check with your account manager which cluster applies to your system. For more information, see Clusters.

2. Create a Generic integration in Mapp Connect. See the full process here: Create an Integration.

   Keep the Integration ID and the Secret ready. You will need them to perform the next steps.

   • Integration ID: Each integration has a unique ID. The integration ID is available on the overview tab of your integration settings.

   • Integration Secret:  A random secret is available if enabled. This key can be used to sign a REST request using HMAC Authentication (read more here). Generate a secret key and store it in a notepad. This secret will only be visible once. Copy this and save it for future use after regeneration.

3. Once the integration is created, paste the Integration ID in the URL after /integration/. 

   

4. Go to the Pre-Request Script tab and paste the secret key in line 21.
    

5. Click Send and wait for the response.
    

6. Since Mapp Connect is an asynchronous API, there are only two types of responses:

   1. 200: call received

   2. 500: incorrect JSON or wrong authentication credentials

Test API methods

You can test any method that is listed in the collection. All available API calls are listed below.

1. Select the method you want to test from the menu on the left.
    

2. Enter the payload to the Body section and click Send. For more information, see API Endpoints.
    

Available API Methods

Mapp Connect is a simple async API with methods to: