ユーザープッシュ通知（Push to User）

ユーザープッシュ通知（Push to User）は、購読中のトピックへのメッセージをプッシュ通知として受け取る機能です。機能概要については、ユーザープッシュ通知 (Push to User) をご覧ください。

トピックの作成

トピックを作成する例を以下に挙げます。

/* 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;
}

この例では、Thing スコープのトピック myTopic を作成しています。kii_topic_t 構造体の指定方法は kii_bucket_t 構造体と同様です。詳細は Object の作成をご覧ください。

トピックを作成するには、トピックを作成できることを示す CREATE_NEW_TOPIC アクションを許可する ACL エントリーが、対象スコープの ACL に存在する必要があります。Thing のオーナーとなっているユーザーやグループのスコープの ACL には Thing に CREATE_NEW_TOPIC アクションを許可する ACL エントリーはデフォルトでは含まれないため、Thing からトピックを作成するには、事前に ACL の設定を行う必要があります。トピックの講読やメッセージ送信を行う SUBSCRIBE_TO_TOPIC アクションと SEND_MESSAGE_TO_TOPIC アクションも必要に応じて設定してください。

通常、アプリケーションスコープのトピックは、アプリケーション管理者の権限により、REST API または Kii Clould SDK for JavaScript を使って作成します。

トピックの削除

トピックを削除する例を以下に挙げます。

/* 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;
}

パラメーターの指定方法はトピックの作成と同様です。

トピックの講読

あるトピックに興味のあるユーザーは、このトピックを購読することでトピックに送信されたメッセージをプッシュ通知で受信できるようになります。

使用中の Thing の権限でトピックを講読する例を以下に挙げます。

/* 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;
}

パラメーターの指定方法はトピックの作成と同様です。

オーナーとなっているユーザーやグループのトピックはデフォルトで講読できません。講読するには ACL の変更が必要です。

トピックの購読解除

トピックの購読を止めることで、プッシュ通知を止めることができます。

トピックを講読解除する例を以下に挙げます。

/* 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;
}

メッセージの送信

Thing SDK Embedded ではプッシュメッセージの送信をサポートしていませんが、REST API を呼び出すことによって、トピックにメッセージを送信することができます。

Thing SDK Embedded での REST API の呼び出し方法は REST API の実行を、REST API のパラメーターの詳細はメッセージの送信を参照してください。

Thing スコープのトピック myTopic にメッセージを送信する例を以下に挙げます。

#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);

このコードでは、最後の kii.kii_core.response_code が 201 を返した場合、REST API の実行が成功したことを意味します。

メッセージの受信をプッシュ通知として受け取る

プッシュ通知を受け取るには、プッシュ通知の受信ハンドラーを設定します。実装方法は、受信ハンドラーの実装をご覧ください。

プッシュメッセージの例

以下は、Push to User のプッシュ通知を受け取ったとき、受信できるデータのイメージです。Push to User では、通知されたトピック名や、アプリケーションから指定した追加データ（ここでは Key1 = Value1）が含まれる JSON 文字列を、ハンドラーの引数として取得できます。

これらのデータの詳細は、Kii Cloud SDK for Android の Javadoc を参考にしてください。

{
  "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"
}