Push API

Push API allows you to manage device registration and notifications. By sending HTTP request you can register/unregister devices, you can find the number of registered devices and you can delete devices using platform and tag informations. You can also send notification and get the details of sent notification via REST API.

PARAMETERS

X-netmera-api-key :  Netmera API Key. You can get it from the application’s overview page on netmera.com

registrationId :  This is equivalent to the regId in Android and deviceToken in the IOS platform.

platform :  The name of the platform could be “ANDROID”, “IOS” or “WP”.

tags : List of the unique tags to which the device is registered.

latestLocation : Latest location of the registered device. It is an array which has two parameters which are latitude and longitude respectively.

iid : Unique installation id of the device that is generated by Netmera SDK.

timeZone :  Current time zone of the device.

max : Maximum number of the contents returned as the result. Default value is 10.

page : It is used to retrieve the contents of a given page. Default value is 0. If you set page as 1, then it will skip page*max and retrieve the next max items.

title : This is the title of the notification.

notificationMsg : This is the message of the notification you want to send.

richPushHtml : If you want to send rich push notification, then you can add html into this parameter.

customJson : Custom json data which holds key-value pairs and used to send different data as a payload to the push notification. You can send custom data and use its values in the application.

customFields : It is a key-value pairs which is used to add those fields during push user registration. It is also used to filter users during sending push notification.

overrideTags : This is a boolean field whose default value is FALSE. If it is setted as TRUE then new tag list will override the current tag list of the push user.Otherwise it will merge two lists.

showInPushInbox : This is a boolean field to determine to show push notification in push inbox.

Register Device

Following code can be used to register device to get push notification. registrationId and platform are the required fields. You can get registrationId from Apple for IOS devices which is called deviceToken and Google for Android which is equivalent to the regId. platform field could be “ANDROID”, “IOS” or “WP”. You can also set latest location, installation id and time zone of the device while registering. You can group devices by registering them into different tags using the tags field and send notification using the specific tag. You can also add customFields during registration and filter the users with the given custom field(s) during sending notification. There is an optional field namely overrideTags which is used to override older tag list with the new one.

curl -X POST \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
        "registrationId": "${REGISTRATION_ID}",
        "platform": "ANDROID",
        "tags": ["tag1", "tag2"],
        "latestLocation": [latitude, longitude],
        "iid": "${INSTALLATION_ID}",
        "timeZoneHourOffset":"0",
        "customFields": {
            "key1": "value1",
            "key2": "value2"
        },
        "overrideTags" : true
}' \
https://api.netmera.com/push/1.1/registration

If registration is successful, you will get the code 1000 and message OK as a response.

{ "message" : "OK", "code" : 1000 }

In case of exception occurs while registration, following response message will be sent. For example if registrationID is null or empty then you will get following response.

{ "message" : "Registration ID cannot be null nor empty", "code" : 2003 }

Batch Register Device

Following code can be used to register multiple devices at the same time. Instead of registering single device, you can post array of devices for bulk registration. This method will help you to import your devices into Netmera easily.

curl -X POST \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
        "registrations": [
	{
	    "registrationId": "${REGISTRATION_ID}",
	    "platform": "ANDROID",
	    "tags": ["tag11", "tag12"],
	    "latestLocation": [latitude, longitude],
	    "iid": "${INSTALLATION_ID}",
	    "timeZoneHourOffset":"0",
	    "customFields": {
	        "key11": "value11",
	        "key12": "value12"
	    },
	    "overrideTags" : true
	},
	{
	    "registrationId": "${REGISTRATION_ID}",
	    "platform": "IOS",
	    "tags": ["tag21", "tag22"],
	    "latestLocation": [latitude, longitude],
	    "iid": "${INSTALLATION_ID}",
	    "timeZoneHourOffset":"1",
	    "customFields": {
	        "key21": "value21",
	        "key22": "value22"
	    },
	    "overrideTags" : false
	},
	{
	    "registrationId": "${REGISTRATION_ID}",
	    "platform": "WP",
	    "tags": ["tag31", "tag32"],
	    "latestLocation": [latitude, longitude],
	    "iid": "${INSTALLATION_ID}",
	    "timeZoneHourOffset":"2",
	    "customFields": {
	        "key31": "value31",
	        "key32": "value32"
	    },
	    "overrideTags" : true
	}]
}' \
https://api.netmera.com/push/1.1/registration/batch

Send Notification

The following code is used to send notification. It has the title and notificationMsg as required parameters. You can also set the platforms, tags and custom fields to filter the devices. If you do not set those parameters then it will broadcast notification to the all available devices.

curl -X POST \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
        "target" : {
                "platforms": ["ANDROID", "IOS", "WP"],
                "tags": ["tag1", "tag2"],
                "customFields": {
                        "key1": "value1",
                        "key2": "value2"
                }
        },
        "notification" : {
	        "title": "My First Push Notification",
        	"notificationMsg": "My First Push Notification message",
        	"richPushHtml": "<html></html>",
        	"showInPushInbox" : false,
        	"customJson": {
                        "key1": "value1",
                        "key2": "value2"
        	}
        }
}' \
https://api.netmera.com/push/1.2/notification

Send Notification to a Specific Device

You can also send the notification only to a device by specifying the registrationId. If you send notification by using registration Id, there is no need to add platform and tags parameters, they will be discarded.

curl -X POST \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
        "target" : {
                "registrationId": "${REGISTRATION_ID}",
        },
        "notification" : {
	        "title": "My First Push Notification",
        	"notificationMsg": "My First Push Notification message",
        	"richPushHtml": "<html></html>",
                "customJson": {
                    "key1": "value1",
                    "key2": "value2"
                }
        }
}' \
https://api.netmera.com/push/1.2/notification

Send Notification to Segment

You can also send the notification only to a segment by specifying the name of the segment.

curl -X POST \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
        "target" : {
                "platforms": ["ANDROID", "IOS", "WP"],
		 "segments" : ["yourSegmentName"]
        },
        "notification" : {
	        "title": "New Notification",
        	"notificationMsg": "Click here to go app"
        }
}' \
https://api.netmera.com/push/1.2/notification

If notification is sent successfully, you will get the code 1000 and message OK as a response. Sent notification ID will be shown as a response inside the result block.

{
    "message" : "Push notification is sending",
    "code" : 1000,
    "result" : { "notificationId" : "5199eb7244ae79c2d5c59ed7" }
}

In case of exception occurs while sending notification, following response message will be sent. For example, when notification is sent without setting notificationMsg field, you will get the following exception message as a response.

{ "message" : "notificationMsg cannot be null nor empty", "code":2003 }

Send Notification to Location

You can also send the notification that matches with the given location. You can also set other parameters such as tags, custom fields to filter users with location. It will find users that matches with all given parameters. You can filter users by location in two ways. You can either send CIRCLE or BOX push.

Circle Push

CIRCLE push takes one location (lat1, lng1) and a distance as a parameter and by taking given location as a base finds the users located in the given distance far away. Unit of the distance field is KM.

curl -X POST \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
        "target" : {
            "platforms": ["ANDROID", "IOS", "WP"],
            "tags": ["tag1", "tag2"],
            "customFields": {
                "key1": "value1",
                "key2": "value2"
        	},
    	    "pushLocation": {
     	        "lat1": "41.0",
     	        "lng1": "28.0",
     	        "distance" : 100,
    	        "locationType": "CIRCLE"
   	    }
        },
        "notification" : {
	        "title": "My First Push Notification",
        	"notificationMsg": "My First Push Notification message",
        	"richPushHtml": "<html></html>",
                "customJson": {
                    "key1": "value1",
                    "key2": "value2"
        	}
        }
}' \
https://api.netmera.com/push/1.2/notification

Box Push

BOX push takes two locations (lat1, lng1, lat2, lng2) as a parameter and by creating box it finds the users located inside the given box.

curl -X POST \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
        "target" : {
	"platforms": ["ANDROID", "IOS", "WP"],
	"tags": ["tag1", "tag2"],
	"customFields": {
                "key1": "value1",
                "key2": "value2"
        	},
    	"pushLocation": {
     	    "lat1": "41.0",
     	    "lng1": "28.0",
     	    "lat2": "42.0",
     	    "lng2": "29.0",
    	    "locationType": "BOX"
   	}
        },
        "notification" : {
	        "title": "My First Push Notification",
        	"notificationMsg": "My First Push Notification message",
        	"richPushHtml": "<html></html>",
	        "customJson": {
                    "key1": "value1",
                    "key2": "value2"
        	}
        }
}' \
https://api.netmera.com/push/1.2/notification

Get Notification

Following code gets the details of notification by using its ID.

curl -X GET  \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
https://api.netmera.com/push/1.1/notification/{ID}

If notification is get successfully, you will get the code 1000 and message OK as a response. You will get the details of notification inside the result block as shown below.

{
    "message": "OK",
    "result": {
        "notification": {
            "tags": [],
            "message": "Rest Api Push Notification -673537462",
            "customJson": [],
            "notificationId": "519cb40044aefae1c8af1482",
            "title": "Rest Api Push Notification -673537462",
            "results": {
                "ANDROID": {
                    "sendDate": "2013-05-22T15:03:12.025Z",
                    "error": null,
                    "pushStatus": "FINISHED",
                    "finishDate": "2013-05-22T15:06:11.378Z",
                    "successCount": 125000,
                    "failedCount": 1200
                },
                "IOS": {
                    "sendDate": "2013-05-22T15:03:12.025Z",
                    "error": null,
                    "pushStatus": "FINISHED",
                    "finishDate": "2013-05-22T15:06:37.378Z",
                    "successCount": 236000,
                    "failedCount": 2700
                },
                "WP": {
                    "sendDate": "2013-05-22T15:03:12.025Z",
                    "error": null,
                    "pushStatus": "FINISHED",
                    "finishDate": "2013-05-22T15:05:26.378Z",
                    "successCount": 58000,
                    "failedCount": 3200
                }
            },
            "pushStatus": "FINISHED",
            "pushType": "STANDARD",
            "platforms": [
                "ANDROID",
                "IOS",
                "WP"
            ],
            "richPushHtml": null
        }
    },
    "code": 1000
}

pushType can be one of these values: “STANDART”, “RICH”

pushStatus can be one of these values: “DRAFT”, “SENDING”, “FINISHED”, “FAILED”

In case of exception occurs while sending notification, following response message will be sent. For example, when given notificationID is wrong or invalid and requested notification will not found then following error message will be shown.

{ "message" : "Notification with this notificationId does not exist!", "code":2108 }

Get Device Info by ID

You can get the registered device info by running the following code. It gets a registrationId as a parameter. You can get the latest location, tag(s), installation ID and time zone of the device as a response.

curl -X GET  \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
https://api.netmera.com/push/1.1/registration/${REGISTRATION_ID}

If device info is get successfully, you will get the code 1000 and message OK as a response. Device info is shown inside the result block.

{
    "message" : "OK",
    "code" : 1000,
    "result" : {
        "registration" : {
             "tags" : ["tag1","tag2"],
             "platform" : "ANDROID",
             "latestLocation" : {"latitude": 41.0, "longitude": 29.0, "timeZone": 0 },
             "iid" : "e35b3f3d-8e09-4442-aff8-7fc16a0b03f0",
             "udid" : "a88fqsdg8as87rgq87wrg8as8dg78zDf8a98sdf98asd8fa7sdf"	
         }
    }
}

In case of exception occurs while getting device info, following response message will be sent. For example, when the requested deviceID is not registered on our system then following error message will be shown.

{ "message":"The device is not registered", "code":2102 }

Get Device Info by Query

You can get the registered devices’ info which fit the given query by running the following code. You can get the latest location, tag(s), installation ID and time zone of the devices as a response.

curl -X GET  \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-G \
--data-urlencode 'tags = ["tag1", "tag2"]' \
--data-urlencode 'platforms = ["ANDROID", "IOS", "WP"]' \
--data-urlencode 'customFields = {"key1":"value1", "key2":"value2"}' \
--data-urlencode 'max = 10' \
--data-urlencode 'page = 0' \
https://api.netmera.com/push/1.2/registration

If device info is get successfully, you will get the code 1000 and message OK as a response.

{
    "message" : "OK",
    "code" : 1000,
    "result" : {
	"registration" : [{
            "tags" : ["tag1","tag2"],
            "platform" : "ANDROID",
            "customFields": {"key1": "value1", "key2": "value2"},
            "latestLocation" : {"latitude": 41.0, "longitude": 29.0, "timeZone": 0 },
            "registered": true,
            "iid" : "e35b3f3d-8e09-4442-aff8-7fc16a0b03f0",
            "udid" : "a88fqsdg8as87rgq87wrg8as8dg78zDf8a98sdf98asd8fa7sdf"	
        }, {
            "tags" : ["tag3","tag4"],
            "platform" : "IOS",
            "customFields": {"key1": "value1", "key2": "value2"},
            "latestLocation" : {"latitude": 41.0, "longitude": 29.0, "timeZone": 0 },
            "registered": false,
            "iid" : "e35b3f3d-8e09-4442-aff8-7fc16a0b03f1",
            "udid" : "a88fqsdg8as87rgq87wrg8as8dg78zDf8a98sdf98asd8fa7sde"	
        }]
    }
}

In case of exception occurs while getting device info, following response message will be sent.For example, when the requested deviceID is not registered on our system then following error message will be shown.

{ "message":"The device is not registered", "code":2102 }

Get Registration Count

This method is used to find the counts of the registered devices. If you don’t set tags and platforms parameters it will find the counts of the all devices. Otherwise it will find the devices that registered to given tag(s) or given platform(s).

curl -X GET  \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-G \
--data-urlencode 'tags = ["tag1", "tag2"]' \
--data-urlencode 'platforms = ["ANDROID", "IOS", "WP"]' \
https://api.netmera.com/push/1.1/registration/count

If device count is get successfully, you will get the code 1000 and message OK as a response. You will get the device count inside the result block as shown below.

{
    "message" : "OK",
    "code" : 1000
    "result" : { "count" : 4 }
}

In case of exception occurs while getting device info, following response message will be sent. For example, if sended platform names will be invalid then you will get following error message.

{ "message" : "Error occurred while retrieving tags from json array. It is invalid or corrupted", "code" : 2009 }

Unregister Device by ID

The following code unregisters the device by using registrationId. If you do not want to send push notification to any users, you can unregister them from the device list.

curl -X DELETE  \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
https://api.netmera.com/push/1.1/registration/${REGISTRATION_ID}

If device is unregistered successfully, you will get the code 1000 and message OK as a response.

{ "message" : "OK", "code" : 1000 }

In case of exception occurs while unregistering device, following response message will be sent. For example if API Key is invalid then you will get following response.

{ "message" : "API key cannot be null or empty", "code" : 2003 }

Unregister Device by ID & Tag

Following code unregisters the device from the given tag(s). You can still send notification to the remaining tag(s) of the device or you can send broadcast notification if user has no tag.

curl -X DELETE \
-H "X-netmera-api-key: ${API_KEY}" \
-H "Content-Type: application/json" \
-G \
--data-urlencode 'tags = ["tag1", "tag2"]' \
https://api.netmera.com/push/1.1/registration/${REGISTRATION_ID}

If device is unregistered successfully from the given tag(s), you will get the code 1000 and message OK as a response.

{ "message" : "OK", "code" : 1000 }

In case of exception occurs while unregistering device, following response message will be sent.For example if tags data is invalid then you will get following response.

{ "message" : "Error occurred while retrieving json object. It is invalid or corrupted", "code" : 2009 }

March 31, 2015 / parag

Recent Blog Posts
ROI based app marketing for your business
App Indexing: some insights
Categories