Push to User Notification
The Push to User notification feature allows receiving messages sent to a subscribed topic as push notifications. See Push to User Notification for the overview of how it works.
Creating a topic
See the below sample code for creating a topic.
/* Set topic parameters. */
kii_topic_t topic;
memset(&topic, 0x00, sizeof(kii_topic_t));
topic.scope = KII_SCOPE_THING;
topic.scope_id = "VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS";
topic.topic_name = "myTopic";
/* Create the topic. */
result = kii_push_create_topic(&kii, &topic);
if (ret != 0) {
/* Handle the error. */
return;
}
This example creates a topic myTopic in the thing scope. Specify the kii_topic_t structure in the same way as you specify the kii_bucket_t structure. See Creating a KiiObject for more information.
To allow the thing to create a topic, the ACL of the target scope must have an ACL entry which permits the CREATE_NEW_TOPIC action to the thing. The ACL needs to be set in advance because the ACL of the scope of the user or group which owns the thing does not have an ACL entry which permits the CREATE_NEW_TOPIC action to the thing by default. Add ACL entries which permit the SUBSCRIBE_TO_TOPIC and SEND_MESSAGE_TO_TOPIC actions for subscribing to a topic and sending a message as required.
Usually, topics in the application scope are created by using the REST API or the Kii Cloud SDK for JavaScript with the app administrator's privilege.
Deleting a topic
See the below sample code for deleting a topic.
/* Set topic parameters. */
kii_topic_t topic;
memset(&topic, 0x00, sizeof(kii_topic_t));
topic.scope = KII_SCOPE_THING;
topic.scope_id = "VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS";
topic.topic_name = "myTopic";
/* Delete the topic. */
result = kii_push_delete_topic(&kii, &topic);
if (ret != 0) {
/* Handle the error. */
return;
}
Specify the parameters in the same way as you do for creating a topic.
Subscribing to a topic
The user can receive messages sent to a certain topic of interest as push notifications by subscribing to the topic.
See the below sample code for subscribing to a topic with the permission of the thing in use.
/* Set topic parameters. */
kii_topic_t topic;
memset(&topic, 0x00, sizeof(kii_topic_t));
topic.scope = KII_SCOPE_THING;
topic.scope_id = "VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS";
topic.topic_name = "myTopic";
/* Subscribe to the topic. */
result = kii_push_subscribe_topic(&kii, &topic);
if (ret != 0) {
/* Handle the error. */
return;
}
Specify the parameters in the same way as you do for creating a topic.
By default, the thing cannot subscribe to the topics of the user or group which owns the thing. You need to change the ACL to allow the thing to subscribe to such topics.
Unsubscribing from a topic
By unsubscribing from a topic, you can stop push notifications for the topic.
See the below sample code for unsubscribing from a topic.
/* Set topic parameters. */
kii_topic_t topic;
memset(&topic, 0x00, sizeof(kii_topic_t));
topic.scope = KII_SCOPE_THING;
topic.scope_id = "VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS";
topic.topic_name = "myTopic";
/* Unsubscribe from the topic. */
result = kii_push_unsubscribe_topic(&kii, &topic);
if (ret != 0) {
/* Handle the error. */
return;
}
Sending a message
Even though the Thing SDK Embedded does not support sending push messages, you can send a message to a topic by calling the REST API.
See Executing REST API to learn how to call the REST API from the Thing SDK Embedded. See Sending a Push Notification for more information about the REST API parameters.
See the below sample code for sending a message to the myTopic topic in the thing scope.
#define RESOURCE_PATH "/api/apps/" EX_APP_ID "/things/VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS/topics/myTopic/push/messages"
#define CONTENT_TYPE "application/vnd.kii.SendPushMessageRequest+json"
/* Start to create a REST API request. */
result = kii_api_call_start(&kii, "POST", RESOURCE_PATH, CONTENT_TYPE, KII_TRUE);
if (result != 0) {
/* Handle the error. */
return;
}
#define HTTP_BODY "{" \
" \"data\": {" \
" \"Key1\": \"Value1\"," \
" \"Urgent\": false" \
" }," \
" \"sendToDevelopment\": true," \
" \"sendToProduction\": true," \
" \"gcm\": {\"enabled\": true}," \
" \"apns\": {\"enabled\": true}," \
" \"mqtt\": {\"enabled\": true}" \
"}"
/* Append the request body. */
result = kii_api_call_append_body(&kii, HTTP_BODY, strlen(HTTP_BODY));
if (result != 0) {
/* Handle the error. */
return;
}
/* Send the created REST API request. */
result = kii_api_call_run(&kii);
if (result != 0) {
/* Handle the error. */
return;
}
printf("status:%d\n", kii.kii_core.response_code);
If kii.kii_core.response_code at the end of the above code returns 201, it means the REST API has been executed successfully.
Receiving a Push to User notification
Set the reception handler to receive push notifications. See Implementing the Reception Handler to learn how to implement it.
Example of a push message
See below for the sample data received as a Push to User notification. You can get a JSON string, which includes information such as the name of a topic which received a message and additional data (Key1 = Value1 in the example) specified by the application, as an argument of the handler.
See the Javadoc for the Kii Cloud SDK for Android for more information about the data in a Push to User message.
{
"Urgent": "false",
"sender": "th.727f20b00022-e1ba-6e11-18c2-0af88aeb",
"sourceURI": "kiicloud://things/th.727f20b00022-e1ba-6e11-18c2-0af88aeb/topics/myTopic",
"objectScopeType": "APP_AND_THING",
"topic": "myTopic",
"objectScopeAppID": "11111111",
"Key1": "Value1",
"senderURI": "kiicloud://things/th.727f20b00022-e1ba-6e11-18c2-0af88aeb",
"when": 1470109418054,
"objectScopeThingID": "th.727f20b00022-e1ba-6e11-18c2-0af88aeb"
}