Hipalerts API
Welcome to the Hipalerts API! You can use our API to integrate our proximity marketing services to your app. The API connects to the Hipalerts Dashboard, a Web interface where you can configure business rules for setting up geofence and push notification campaigns. Your application will then download and execute these rules.
The Hipalerts API is RESTful. It uses predictable, resource-oriented URLs and HTTP response codes to indicate API errors. All API responses return JSON.
Register for an Account
To obtain access to the Hipalerts API, click the “Get Started” button and register for an account. A Hipalerts account allows you to:
- Access the Hipalerts API
- Create individual app identifiers for collating the geofences applicable to a client app
- Use a Web-based dashboard to register products and campaigns
- Manage the configurations of your geofences
- View and export analytics
- Maintain your profile and billing information
After you submit the form we’ll reach out shortly to help you set-up a secure account.
App Requirements
- Enable background location services and require app to request user permission to allow access to user’s location even when not using the app.
- Require app to request user permission to receive push notifications.
Create Test Data
We recommend that you create test data to verify that the API has been successfully integrated into your app. For example, configure test geofences and push notifications by creating campaigns. This will allow you to practice triggering notifications, handle any custom action callbacks, and observe activity logs before you push the changes to your live app.
How to Integrate the Hipalerts API into your app
The process begins with the Hipalerts Dashboard, a Web interface where you can configure business rules for geofences and campaigns. Your application will then download and execute these rules.
Creating Products
Products are the entities that Hipalerts will display in the app when a user crosses a geofence and opens a notification. You can manage the list of your products by providing Product Metadata for each product, or by using batch JSON import.
How to create Product Metadata for a single product:
- At the top of the Hipalerts Dashboard, click the tab Developer > Manage Products. Then click the Add a Product button.
- Next you will enter Product Metadata, such as title, cover image URL, and short description of the product. In the Metadata in JSON format field, enter the technical information that will be sent in the body of the APN notification, in JSON format. You can use any key-pairs you want as long as it’s handled in your app. Here are three example key-pairs you could use:
- Description – The message content.
- original_id – A unique ID for the product.
- Details – The metadata for the product. This can be anything that helps the third-party app identify which product it should display to the user. An example of the structure to use when creating Product Metadata in JSON format:
- [
{
“original_id”: “EXID-001”,
“title”: “Excellent Product”,
“description”: “Description of product #001”,
“cover_url”: “http://example.com/sample.jpg”,
“data”: {
“field_1”: “value”,
“filed_2”: [“value”, “value”, “value”]
}
},
{
“original_id”: “EXID-004”,
“title”: “Magnificient Product”,
“description”: “Description of product #004”,
“cover_url”: “http://example.com/sample.jpg”,
“data”: {
“field_1”: “value”,
“filed_2”: [“value”, “value”, “value”]
}
},
{
“original_id”: “EXID-021”,
“title”: “Moderate Product”,
“description”: “Description of product #021”,
“cover_url”: “http://example.com/sample.jpg”,
“data”: {
“field_1”: “value”,
“filed_2”: [“value”, “value”, “value”]
}
},
{
“original_id”: “EXID-043”,
“title”: “Unexpectable Product”,
“description”: “Description of product #043”,
“cover_url”: “http://example.com/sample.jpg”
}
] - original_id is a very important field. Hipalerts tracks records by this ID. After each import Hipalerts checks what records haven’t been exported. So, if Hipalerts finds that some records are absent in the import file, then these records will be marked as deleted ones. We suggest that you use some internal ID from your system as an original_id.
- Click Save Changes.
How to Create Product Metadata by a Batch Import
Alternatively, you can import a JSON file with Product Metadata for all of your products. A sample JSON file can be downloaded here.
To import a JSON Product Metadata file:
- At the top of the Hipalerts Dashboard, click the tab Developer > Manage Product. Then click the Import Products button.
- Select a file
Integration Steps
- Next, you’ll need to share your APN Developer Certificate and APN Production Certificate numbers with Hipalerts administrators. You do this in the API Settings section. Hipalerts will automatically generate a unique application key for you. This key will authorize access to Hipalerts’s servers from your subsystems. Please keep your application key secure.
- Change your app’s code so that it will send user locations to the Hipalerts API.
- Change the app’s code to enable it to receive Product Metadata information via Apple and/or Google Play push notifications.
API Errors
The API uses HTTP response codes to indicate the success or failure of a request. Generally speaking, 200-level codes indicate success, 400-level codes indicate an error that failed on the information provided (e.g., a required parameter was omitted, etc.), and 500-level codes indicate an error with Hipalerts’s servers (these are rare).
Reference
Request Headers
It is important to:
- provide your application key in each request via X-Hipalerts-Application HTTP header.
- know that each API request of your app requires special HTTP headers.
{
“X-Hipalerts-Application”: “Your API application key”,
“Authorization”: “bearer <oauth token>”,
“Content-Type”: “application/json”,
“Accept”: “application/json”
}
The Authorization header provides bearer an OAuth access token that the App has to receive during a User’s sign in process.
In addition you can provide an optional pair of headers, that describes User’s device.
{
“X-API-Device”: “Device and system version string”,
“X-API-Client”: “The string describes name of the App and it’s version”
}
Guest Login
Hipalerts tracks the location of each user in order to deliver notifications based on where they are. To do that, we need to register the user on our side by requesting a guest token for the user of the app the first time.
Each request to the protected API needs to be sent with an access token, which can be obtained by the guest token assertion flow:
POST /api/v4/mobile/wl/oauth/token
The application needs to pass the following parameter in the request:
{
“grant_type”: “guest”
}
Response:
{
“access_token”: “495f2855deba92fe78….b1bc2367abea2ae”,
“token_type”: “bearer”,
“created_at”: 1444626678
}
Track User Location
POST /api/v4/mobile/wl/account/location
This allows for sending user locations to the Hipalerts server so that we may track them. Using this gathered information, the server will send relevant notifications to the user via the client’s app.
Parameters
{
“locations”: [
{
“latitude”: 53.506623995,
“longitude”: 49.276481866,
“occurred_at”: 1468997455
},
{“latitude”: 52.506623995, “longitude”: 43.276481866, “occurred_at”: 1468997855},
…
],
“device_type”: “test_iphone”, // optional, could be test_iphone, iphone or Android, default: ‘iphone’
“device_token”: “….”,
“force”: true // optional, send location without delay
}
Sending Device Token Separately
Sometimes the App doesn’t need to send location updates at all. But server side requires actual device tokens to be able to send push notifications for different segments. To accomplish this goal the App needs to send device token to the following endpoint:
PATCH /api/v4/mobile/wl/account/update_device_token
Parameters
{
“device_type”: “test_iphone”, // optional, could be test_iphone, iphone or android, default: ‘iphone’
“device_token”: “….”
}
Push Notification Format
When you create a push or geofence campaign, the notification deep links to a particular screen in your application. This may be the “home” page, a specific product page, a URL or a place on a map, etc.
Your application will receive additional metadata from Hipalerts with each push notification. For iOS this metadata is contained in aps.custom dictionary. For Android, this metadata is contained in received intent and available via getExtra methods.
Metadata structure:
{
“object_type”: “MetaProduct”,
“object”: {
“id”: 123,
“title”: “Title of your product”,
“meta”: {
// any product meta information you imported into Hipalerts
}
},
“notification_id”: 0
}
Creating Campaigns
Campaigns are the messages you want to send to users who enter specific geofences. Enter your campaigns using the Hipalerts Dashboard. As part of this process, the system will prompt you to enter the specific Product Metadata it should send to your app’s users, and under what conditions.
Track User Events
POST /api/v4/mobile/wl/account/track_event
Allows to track what user’s are doing in the app.
Parameters
{
“payload”: {
… // Custom data, which is specific for each event.
},
“event”: “some_event_name”, // Event name to track
“device_type”: <“iphone”|”android”>
}
Possible events for this type of integration are: open_notification, signup_complete
Manage User Account
Register New User
To register a new user account, the App has to send the new user’s credentials.
POST /api/v4/mobile/wl/users
Params:
{
“username”: “Marko Ball”,
“email”: “marco@gmail.com”,
“password”: “123456”,
“password_confirmation”: “123456”,
}
Success response:
{
“user”: {
“id”: 1,
“email”: “marco@example.com”,
“username”: “Marko Holywarez”
}
}
Get Account Information
GET /api/v4/mobile/wl/account
Response
{
“email”: “user@email”,
“id”: “some id”,
“username”: “user.username”,
“company_name”: “user.company_name”,
“phone”: “user.phone”
}
Delete User Account
DELETE /api/v4/mobile/wl/account
Parameters
email has to match an email of current user, that means you can’t remove another user here.
{
“email”: “Email of user to be removed”,
“password”: “Password of that user”
}
Sign In Process
Before requesting user related API endpoints, App has to obtain access token. Hipalerts supports two ways to do that: via login/password, and via Facebook.
Password grant flow
To interact with protected API that requires user, application needs to obtain access token:
POST /api/v4/mobile/wl/oauth/token
Application needs to pass the following parameter in request:
{
“grant_type”: “password”,
“username”: “marco@gmail.com”,
“password”: “123456”,
}
Response:
{
“access_token”: “495f2855deba92fe78….b1bc2367abea2ae”,
“token_type”: “bearer”,
“created_at”: 1444626678
}
Assertion grant flow
To interact with protected API that requires user, application needs to obtain access token:
POST /api/v4/mobile/wl/oauth/token
Application needs to pass the following parameter in request:
{
“grant_type”: “assertion”,
“assertion_type”: “facebook”, // provider type
“assertion”: “some_token”, // credentials token returned by oAuth authorization
}
Response:
{
“access_token”: “495f2855deba92fe78….b1bc2367abea2ae”,
“token_type”: “bearer”,
“created_at”: 1444626678
}
