Notification - Create
|
Create a new notification. This operation can be performed at either the application or device level. Application-level notification messages have the option to filter the device recipients by specifying either a tag list, a device list, or both within the xml request. Additionally, tags can also be included as a query parameter. If a request is sent with multiple tags, devices that satisify any of the tags will receive the message. For example, if device 1 is tagged with "italian" and "mexican", it will receive a notification message with tags"chinese" and "italian". Device-level notification messages do not have option of sending requests using tag or device lists.
|
Query String Parameters (optional, applicable to messages sent at the application level)
|
Field
|
Value
|
| tags |
tag1|tag2|tag2 |
Request Elements
| Parameter |
Type |
Length |
Description |
Request URI Example
https://api.ilime.com/v1/accounts/1/apps/1/device/dev-msgs/2345
https://api.ilime.com/v1/accounts/1/apps/1/dev-msgs
· Any notification can contain an alert, a badge number, and/or a
sound. At least one of these must be present (if not you’ll get a 400
error).
· The alert portion can take two forms, text or an alert dictionary
which allows picking a localized string (with arguments) on the
device. Only one of these can be set; if alertText and alertDict are
both set, you’ll get a 400 error.
· An alertText is a simple string (this is what we’ve been using so
far).
· The alertDict can contain a body (works just like alertText), plus
actionLocKey and locKey which are key names for localizable strings
(for the action button and the message text, respectively); these
cause localized string lookups on the device. The locArgs parameter
is a list of strings (any number) for placeholder substitution in the
looked-up text.
· A badgeNumber must be a positive integer. · A sound is just a
string which specifies the file name of a sound to play.
· All of the above comments relate to NotificationContent; this is
wrapped in a NotificationRequest which is like an envelope with
additional delivery info. Most of these fields are set in the back
end and should not be sent. The only ones you’ll need to set are the
content, isActive, and schedule.
XML Example
<notificationRequest>
<notificationContent>
<alertText>Simple scheduled message</alertText>
</notificationContent>
<scheduleItems>
<scheduleItem>
<startDate>2009-07-31</startDate>
<notificationTimeGMT>17:02</notificationTimeGMT>
<recurrenceType>NONE</recurrenceType>
</scheduleItem>
</scheduleItems>
</notificationRequest>
Or
<notificationRequest>
<notificationContent>
<alertDict>
<actionLocKey>VIEW_BUTTON_KEY</actionLocKey>
<locKey>MESSAGE1_KEY</locKey>
<locArg>Test1</locArg>
<locArg>Test2</locArg>
</alertDict>
</notificationContent>
<scheduleItems>
<scheduleItem>
<startDate>2009-07-31</startDate>
<notificationTimeGMT>11:00</notificationTimeGMT>
<recurrenceType>NONE</recurrenceType>
</scheduleItem>
</scheduleItems>
</notificationRequest>
XML Example using devices and tags (Application Level only)
<notificationRequest>
<notificationContent>
<alertText>TestDevices</alertText>
</notificationContent>
<deviceTags>
<deviceTag>
<tag>Alaska</tag>
</deviceTag>
<deviceTag>
<tag>Hawaii</tag>
</deviceTag>
</deviceTags>
<useDev>true</useDev>
<isComplete>false</isComplete>
<isActive>true</isActive>
<devices>
<device id="62"/>
<device id="49"/>
</devices>
</notificationRequest>
JSON Example
{
"notificationRequest":{
"notificationContent":{
"alertText":"Simple scheduled message"
},
"scheduleItems":{
"scheduleItem":{
"notificationTimeGMT":"17:02",
"recurrenceType":"NONE",
"startDate":"2009-07-31"
}
}
}
}
Or
{
"notificationRequest":{
"notificationContent":{
"alertDict":{
"actionLocKey":"VIEW_BUTTON_KEY",
"locArg":[
"Test1",
"Test2"
],
"locKey":"MESSAGE1_KEY"
}
},
"scheduleItems":{
"scheduleItem":{
"notificationTimeGMT":"11:00",
"recurrenceType":"NONE",
"startDate":"2009-07-31"
}
}
}
}
JSON Example using devices and tags (Application Level only)
{
"notificationRequest":{
"notificationContent":{
"alertText":"TestDevices"
},
"deviceTags":{
"deviceTag":[
{
"tag":"Alaska"
},
{
"tag":"Hawaii"
}
]
},
"useDev":true,
"isComplete":false,
"isActive":true,
"devices":{
"device":[
{
"@id":"62"
},
{
"@id":"49"
}
]
}
}
}
Errors
Returns standard error response codes. See Error Codes.
Example Source Code: C#
using
System;
using
System.IO;
using
System.Net;
using
System.Text;
namespace
iLimeCSharpSampleCode
{
class
Program
{
const
string
UserName =
"userName"
;
const
string
PassWord =
"passWord"
;
static
void
Main(
string
[] args)
{
#region
README
/*
* To Use The C# Samples
*
* 1. Change the UserName and PassWord constant values
*
* 2. Replace the accountid value in the calls below with your accountid (found on the
* Accounts tab in the Admin tool).
*
* 3. To register an application for your account, uncomment the CreateApplication() call below
* and replace the account id with your account id. Also, change the Xml in the CreateApplication method to reflect the your required
* application attributes.
*
* 4. To send a message through the Apple development environment at the application level, uncomment the SendDevelopmentApplicationMessage() call below
* and replace the parameters with your accountid and applicationid, respectively.
*
*/
#endregion
//string xmlResponse = GetAccount(accountid);
//CreateApplication(accountid);
//SendDevelopmentApplicationMessage(accountid, applicationid);
}
#region
GetAccount
///
<summary>
///
Retrieves account iformation. Returns XML based on API documentation.
///
</summary>
///
<param name="accountId"></param>
static
void
GetAccount(
int
accountId)
{
Uri
uri =
null
;
try
{
uri =
new
Uri
(
string
.Format(
"
https://api.ilime.com/v1/accounts/{0}
"
, accountId));
var
payload =
new
RequestPayload
{ UserName = UserName, Password = PassWord, Uri = uri, Xml =
string
.Empty };
payload = PerformWebRequest(payload,
HTTPMethodEnum
.Get);
Console
.WriteLine(payload.ResponseCode);
Console
.WriteLine(payload.Response);
}
catch
(
Exception
ex)
{
Console
.WriteLine(ex.Message);
Console
.WriteLine(
"Method: GET"
);
Console
.WriteLine(
"Uri: "
+ uri);
}
finally
{
Console
.ReadLine();
}
}
#endregion
#region
CreateApplication
///
<summary>
///
Creates a new application within an account.
///
</summary>
///
<param name="accountId"></param>
private
static
void
CreateApplication(
int
accountId)
{
Uri
uri =
null
;
string
xml =
null
;
try
{
uri =
new
Uri
(
string
.Format(
"
https://api.ilime.com/v1/accounts/{0}/apps
"
, accountId));
xml =
"<application>"
+
"<name>Application Name</name>"
+
"<uriFriendlyName>name</uriFriendlyName>"
+
"<isActive>true</isActive>"
+
"</application>"
;
var
payload =
new
RequestPayload
{ UserName = UserName, Password = PassWord, Uri = uri, Xml = xml };
payload = PerformWebRequest(payload,
HTTPMethodEnum
.Post);
Console
.WriteLine(payload.ResponseCode);
Console
.WriteLine(payload.Response);
}
catch
(
Exception
ex)
{
Console
.WriteLine(ex.Message);
Console
.WriteLine(
"Method: POST"
);
Console
.WriteLine(
"Uri: "
+ uri);
Console
.WriteLine(
"Xml: "
+ xml);
}
finally
{
Console
.ReadLine();
}
}
#endregion
#region
SendDevelopmentApplicationMessage
///
<summary>
///
Sends a message to every device registered with the application.
///
</summary>
///
<param name="accountId"></param>
///
<param name="applicationID"></param>
private
static
void
SendDevelopmentApplicationMessage(
int
accountId,
int
applicationID)
{
Uri
uri =
null
;
string
xml =
null
;
try
{
uri =
new
Uri
(
string
.Format(
"
https://https://api.ilime.com/v1/accounts/{0}/apps/{1}/dev-msgs
"
, accountId, applicationID));
xml =
"<notificationRequest><notificationContent>"
+
"<alertText>This is a sample message</alertText>"
+
"<badge>4</badge>"
+
"<sound>explode.wav</sound>"
+
"</notificationContent></notificationRequest>"
;
var
payload =
new
RequestPayload
{ UserName = UserName, Password = PassWord, Uri = uri, Xml = xml };
payload = PerformWebRequest(payload,
HTTPMethodEnum
.Post);
Console
.WriteLine(payload.ResponseCode);
Console
.WriteLine(payload.Response);
}
catch
(
Exception
ex)
{
Console
.WriteLine(ex.Message);
Console
.WriteLine(
"Method: POST"
);
Console
.WriteLine(
"Uri: "
+ uri);
Console
.WriteLine(
"Xml: "
+ xml);
}
finally
{
Console
.ReadLine();
}
}
#endregion
#region
PerformWebRequest
static
RequestPayload
PerformWebRequest(
RequestPayload
data,
HTTPMethodEnum
httpMethod)
{
try
{
var
encoding =
new
UTF8Encoding
();
var
request = (
HttpWebRequest
)
WebRequest
.Create(data.Uri);
request.Method =
Enum
.GetName(
typeof
(
HTTPMethodEnum
), httpMethod);
request.Headers[
"Authorization"
] =
"Basic "
+
Convert
.ToBase64String(
new
UTF8Encoding
().GetBytes(data.UserName +
":"
+ data.Password));
request.ContentType =
"application/xml"
;
if
(!
string
.IsNullOrEmpty(data.Xml))
{
request.ContentLength = encoding.GetByteCount(data.Xml);
using
(
Stream
reqStm = request.GetRequestStream())
{
reqStm.Write(encoding.GetBytes(data.Xml), 0,
encoding.GetByteCount(data.Xml));
}
}
else
request.ContentLength = 0L;
using
(
var
response = (
HttpWebResponse
)request.GetResponse())
{
data.Headers = response.Headers;
data.ResponseCode = response.StatusCode;
var
streamReader =
new
StreamReader
(response.GetResponseStream(),
Encoding
.UTF8);
data.Response = streamReader.ReadToEnd();
response.Close();
streamReader.Close();
}
}
catch
(
WebException
webException)
{
WebResponse
webResponse = webException.Response;
if
(webResponse !=
null
)
{
var
reader =
new
StreamReader
(webResponse.GetResponseStream(),
Encoding
.UTF8);
data.Response = reader.ReadToEnd();
webResponse.Close();
reader.Close();
}
throw
new
Exception
(webException.Message, webException.InnerException);
}
return
data;
}
#endregion
internal
enum
HTTPMethodEnum
{
Delete = 0,
Get = 1,
Post = 2,
Put = 3
}
}
#region
RequestPayload Class
internal
class
RequestPayload
{
public
Uri
Uri {
get
;
set
; }
public
string
Response {
get
;
set
; }
public
string
UserName {
get
;
set
; }
public
string
Password {
get
;
set
; }
public
string
Xml {
get
;
set
; }
public
HttpStatusCode
ResponseCode {
get
;
set
; }
public
WebHeaderCollection
Headers {
get
;
set
; }
public
WebException
ResponseException {
get
;
set
; }
}
#endregion
}