API v1.3 ガイド - NHN Cloud 使用ガイド

Notification > Push > API v1.3ガイド

APIテスト

[CONSOLE] > [Notification] > [Push] > [APIs]タブで行えます。

Secret Key

Header
X-Secret-Key: [a-zA-Z0-9]{8}

[CONSOLE] > [Notification] > [Push] > [URL & AppKey]で作成できます。

Response

[Response HTTP Status Code]

200 OK.
すべてのAPIリクエストに対して200 OKレスポンスを返します。詳細なレスポンス結果は、Response BodyのHeaderで確認できます。

[Response Header]

{
    "header" : {
        "isSuccessful" : true,
        "resultCode": 0,
        "resultMessage" : "Success."
    }
}

[resultCode, resultMessage]

isSuccessful	resultCode	resultMessage
true	0	Success.
false	40001	Client Error. Wrong URI.
false	40002	Client Error. Unavailable field value.
false	40003	Client Error. Bad request. Check your request parameter or body.
false	40004	Client Error. Target length is exceeded. CHANNEL: 100, UID: 10,000.
false	40005	Client Error. Content length is exceeded.
false	40006	Client Error. Wrong target format. Clound't read two target types at once. Send a target, channels or uids at once.
false	40007	Client Error. Invalid certificate.
false	40008	Client Error. Invalid APNS certificate.
false	40009	Client Error. Invalid APNS Sandbox certificate.
false	40101	Client Error. Permission denied. Access is not allowed.
false	40102	Client Error. Unavailable appkey.
false	40402	Client Error. No messages to send in body.
false	40403	Client Error. No target in body.
false	40404	Client Error. Not found certificate.
false	40405	Client Error. Not found instance.
false	40406	Client Error. Not found reservation.
false	40407	Client Error. Unavailable reservation.
false	40408	Client Error. Not found channel.
false	40409	Client Error. Not found token.
false	40010	Client Error. Invalid Tencent certificate.
false	40011	Client Error. Bad request. Check your content.
false	40012	Client Error. Expired APNS certificate.
false	40013	Client Error. Duplicate certificate.
false	40014	Client Error. Wrong message type. Check contact or removeGuide.
false	40015	Client Error. Wrong reservationDays.
false	50001 ～ 50501	Internal Error. Please report this. 'http://cloud.toast.com/support/qaa'.

トークン

トークンの登録

[Method, URL]

POST https://api-push.cloud.toast.com/push/v1.3/appkey/{appkey}/tokens
Content-Type: application/json;charset=UTF-8

[Request Body]

{
  "channel": "default",
  "oldToken": "oldToken",
  "token": "token",
  "isNotificationAgreement": true,
  "isAdAgreement": true,
  "isNightAdAgreement": true,
  "pushType": "GCM",
  "timezoneId": "Asia/Seoul",
  "uid": "uid",
  "country": "KR",
  "language": "ko"
}

[Response Body]

{
    "header" : {
        "isSuccessful" : true or false,
        "resultCode": 0,
        "resultMessage" : "Success."
    }
}

Parameter	Usage
token	Required, String	Token. 最大1,600文字。
oldToken	Optional, String	Old Token. 最大1,600文字。
channel	Optional, String	Channel name. 最大50文字。
pushType	Required, String	GCM, APNS, APNS_SANDBOX, TENCENT, ADM
isNotificationAgreement	Required, Boolean	true or false
isAdAgreement	Required, Boolean	true or false
isNightAdAgreement	Required, Boolean	true or false
timezoneId	Required, String	Area/Name. IANA time zone database.
country	Required, String	ISO 3166-1 alpha-2, ISO 3166-1 alpha-3. 3文字。
language	Required, String	ISO 639-1, ISO 639-2, iOS(language code + script code). 8文字。
uid	Required, String	User ID、64文字。

トークン登録時、すでにトークンが登録されている場合は、トークン基準で別の情報がアップデートされる。
もしトークンが変更された場合は、oldTokenに既存トークンを、 tokenに新しいトークンを設定して登録すると新しいトークンにアップデートされる。
トークン登録時にChannelを登録すると、メッセージ送信時に特定Channelに送信できる。必須ではなく、定義しなければ"default"で登録される。
トークンは1つのChannelにのみ属すことができる。
"isNotificationAgreement"プッシュメッセージの受信に同意するかどうか、"isAdAgreement"広告性プッシュメッセージを受信するかどうか。"isNightAdAgreement"夜間広告性プッシュメッセージを受信するかどうかを表します。
例えば、すべてのプッシュメッセージの受信を希望する場合は、フィールド3個をすべてtrueに設定してください。プッシュメッセージのみ受信する場合は、 "isNotificationAgreement"のみtrueに設定してください。
受信に同意するかどうかは、韓国情報通信網法の規定(第50条から第50条の8)に従う。 KISAガイドリンク
 法令リンク
ネットワーク状態が良くないか、複数の理由によるレスポンス遅延が発生することがある。モバイルアプリケーション起動への影響を最小化するためにTimeoutを短く設定し、起動するたびにトークンを登録することを推奨する。
トークンはセキュリティ的なイシュー、アプリアップデート、削除など、さまざまな理由で再発行されることがある。頻繁に変更されることはないが、受信率を高めるため、起動するたびに最新トークンを登録することを推奨する。
アプリ削除などでトークンが満了してもすぐにGCM、APNSサーバーに適用されず、アプリ削除後にプッシュメッセージを送信した時、送信が成功することがある。

トークン照会

a. トークンとプッシュタイプでトークン照会

[Method, URL]

GET https://api-push.cloud.toast.com/push/v1.3/appkey/{appkey}/tokens?token={token}&pushType={pushType}
Content-Type: application/json;charset=UTF-8

[Response Body]

{
    "token" : {
        "channel": "default",
        "pushType" : "GCM",
        "isNotificationAgreement": true,
        "isAdAgreement": true,
        "isNightAdAgreement": true,
        "timezoneId" : "Asia/Seoul",
        "country": "KR",
        "language": "ko",
        "uid" : "User ID",
        "token" : "Token"
    },
    "header" : {
        "isSuccessful" : true or false,
        "resultCode": 0,
        "resultMessage" : "Success."
    }
}

b. uidでトークン照会

[Method, URL]

GET https://api-push.cloud.toast.com/push/v1.3/appkey/{appkey}/uids/{uid}/tokens
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}

[Response Body]

{
    "tokens": [{
        "channel": "default",
        "pushType" : "GCM",
        "isNotificationAgreement": true,
        "isAdAgreement": true,
        "isNightAdAgreement": true,
        "timezoneId" : "Asia/Seoul",
        "country": "KR",
        "language": "ko",
        "uid" : "User ID",
        "token" : "Token"
    }],
    "header" : {
        "isSuccessful" : true or false,
        "resultCode": 0,
        "resultMessage" : "Success."
    }
}

Secret Keyが必要なAPIで、サーバーで呼び出される必要があります。

メッセージ

※ APIで送信したプッシュメッセージはコンソールとメッセージ照会APIで照会できません。

メッセージ送信

[Method, URL]

POST https://api-push.cloud.toast.com/push/v1.3/appkey/{appkey}/messages
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}

[Request Body]

{
    "target" : {
        "type" : "ALL"
    },
    "content" : {
        "default" : {
            "title": "title",
            "body": "body"
        }
    },
    "messageType" : "NOTIFICATION"
}

[Response Body]

{
    "message" : {
        "messageId" : long
    },
    "header" : {
        "isSuccessful" : true or false,
        "resultCode": 0,
        "resultMessage" : "Success."
    }
}

Parameter	Usage
target.type	Required, String	ALL, CHANNEL, UID
target.to	Optional, String Array	target.typeがCHANNELの場合は100個、 UIDは10,000個。
target.pushTypes	Optional, String Array	GCM, APNS, APNS_SANDBOX, TENCENT, ADM
target.countries	Optional, String Array	ISO 3166-1 alpha-2, ISO 3166-1 alpha-3. 3 bytes.
content	Required, Map	8192 bytes
content.default	Required, Map
content.default.title	Optional, String
content.default.body	Optional, String
messageType	Required, String	NOTIFICATION, AD
contact	Optional, String	messageTypeがADの場合に必要。
removeGuide	Optional, String	messageTypeがADの場合に必要。
timeToLive	Optional, Number	単位は分。範囲は0(無制限)含む1以上。基本値は60。
isStored	Optional, Boolean	メッセージを保存するかどうか。デフォルト値はfalse。

"target.pushTypes"フィールドに特定プッシュタイプでのみメッセージを送信できる。定義しなければ、すべてのプッシュタイプ、 GCM、APNS、APNS_SANDBOX、TENCENT、ADMに送信する。
"target.countries"フィールドが"['KR', 'JP']"の場合、トークン国コードが"KR"または"JP"のTokenに送信する。
"content.default"フィールドは必須で、"content"フィールドについての詳細は下記[共通メッセージフォーマット]を参照。
メッセージを広告タイプ、"messageType": "AD"に送る場合、"contact"、"removeGuide"フィールドを必ず含める必要がある。 "contact"フィールドに連絡先を入力する必要があり、"removeGuide"フィールドに受信解除方法について入力する必要がある。
timeToLiveフィールドを設定すると、設定した時間以上に送信が遅延する場合、自動的に失敗処理される。

["target" Example]

"target.type"が"ALL"の場合、"target.to"は必要ない。
Request Body
{
    "target" : {
        "type" : "ALL"
    },
    "content" : {
        "default" : {
            "title": "title",
            "body": "body"
        }
    }
}
"target.type"が"UID"または"CHANNEL"の場合、"target.to"に送信するuidまたはchannel nameを入力する必要がある。
Request Body
{
    "target" : {
        "type" : "UID",
        "to" : ["uid-01", "uid-02"]
    },
    "content" : {
        "default" : {
            "title": "title",
            "body": "body"
        }
    }
}

["messageType" Example]

広告性プッシュメッセージではなく、一般通知プッシュメッセージで送信する場合、
"messageType"を"NOTIFICATION"にして、 "contact"、"removeGuide"は入力しない。
Request Body
{
    "target" : {
        "type" : "ALL"
    },
    "content" : {
        "default" : {
            "title": "title",
            "body": "body"
        }
    },
    "messageType" : "NOTIFICATION"
}
広告性プッシュメッセージで送る場合、 "messageType"を"AD"にして、"contact"に連絡先、
"removeGuide"に受信同意撤回方法を入力する。
Request Body
{
    "target" : {
        "type" : "ALL"
    },
    "content" : {
        "default" : {
            "title": "title",
            "body": "body"
        }
    },
    "messageType" : "AD",
    "contact" : "連絡先",
    "removeGuide" : "受信解除方法"
}

共通メッセージ

API v1.3から共通メッセージ形式をサポートする。 "content"に下記表の通りにメッセージを作成すると、各プッシュタイプに合わせてメッセージが作成され、送信される。

Reserved Word	Platform	Usage	GCM	APNS	TENCENT	ADM
title	Android, iOS Watch, Tencent, ADM	Optional, String	data.title	aps.alert.title	title	data.title
body	Android, iOS, Tencent, ADM	Optional, String	data.body	aps.alert.body	content	data.body
title-loc-key	iOS	Optional, String	-	aps.alert.title-loc-key	-	-
title-loc-args	iOS	Optional, Array of Strings	-	aps.alert.title-loc-args	-	-
action-loc-key	iOS	Optional, String	-	aps.alert.action-loc-key	-	-
loc-key	iOS	Optional, String	-	aps.alert.loc-key	-	-
loc-args	iOS	Optional, Array of String	-	aps.alert.loc-args	-	-
launch-image	iOS	Optional, String	-	aps.alert.launch-image	-	-
badge	iOS	Optional, Number	-	aps.badge	-	-
sound	Android, iOS, Tencent, ADM	Optional, String	data.sound	aps.sound	custom_content.sound	data.sound
content-available	iOS	Optional, String	-	aps.content-available	-	-
category	iOS	Optional, String	-	aps.category	-	-
mutable-content	iOS	Optional, String	-	aps.mutable-content	-	-
consolidationKey	ADM	Optional, String	-	-	-	consolidationKey
expiresAfter	ADM	Optional, Number	-	-	-	expiresAfter

その他のユーザーが定義したWordは、次のようにCustom Key/Valueフィールドに入る。

Reserved Word	Platform	Usage	GCM	APNS	TENCENT	ADM
customKey	Android, iOS, Tencent, ADM	Optional, Object, Array, String, Number	data.customKey	customKey	custom_content.customKey	data.customKey

["content" Example]

"content.default"は必須。下記"content.ko"、"content.ja"は、トークンの言語コード値。
該当トークンの言語コードに合わせてメッセージが送信される。
Request Body
{
    "target" : {
        "type" : "ALL"
    },
    "content" : {
        "default" : {
            "title": "title",
            "body": "body",
            "badge": 1,
            "key": "value"
        },
        "ko" : {
            "title": "タイトル",
            "body": "内容"
            "key": "値"
        },
        "ja" : {
            "title": "タイトル",
            "body": "プッシュ・メッセージ"
        }
    },
    "messageType" : "NOTIFICATION"
}
"ko" GCMメッセージ
 {
    "data": {
        "title": "タイトル",
        "body": "内容",
        "key": "値"
    }
}
"ja" GCMメッセージ
 {
    "data": {
        "title": "タイトル",
        "body": "プッシュ・メッセージ",
        "key": "value"
    }
}
"ko" APNSメッセージ
{
    "aps": {
        "alert": {
            "title": "タイトル",
            "body": "内容"
        },
        "badge": 1
    },
    "key": "値"

}
"ja" APNSメッセージ
{
    "aps": {
        "alert": {
            "title": "タイトル",
            "body": "プッシュ・メッセージ"
        },
        "badge": 1
    },
    "key": "value"
}
"ko" TENCENTメッセージ
 {
    "title": "タイトル",
    "body": "内容",
    "custom_content": {
        "key": "値"
    }
}
"ja" TENCENTメッセージ
 {
    "title": "タイトル",
    "body": "プッシュ・メッセージ",
    "custom_content": {
        "key": "value"
    }
}
"ko" ADMメッセージ
{
  "data":{
    "title":"タイトル",
    "body":"内容",
    "customKey":"値"
  },
  "consolidationKey":"",
  "expiresAfter":60
}
"ja" ADMメッセージ
{
  "data":{
    "title":"タイトル",
    "body":"プッシュ・メッセージ",
    "customKey":"value"
  },
  "consolidationKey":"",
  "expiresAfter":60
}

メッセージ照会

※コンソールで送信したプッシュメッセージのみメッセージ照会APIで照会できます。

[Method, URL]

GET https://api-push.cloud.toast.com/push/v1.3/appkey/{appkey}/messages/{message-id}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}

[Response Body]

{
  "header": {
    "resultCode": 0,
    "resultMessage": "SUCCESS",
    "isSuccessful": true
  },
  "message": {
    "messageId": 42983,
    "messageType": "NOTIFICATION",
    "target": {
      "type": "ALL",
      "pushTypes": [
        "GCM"
      ]
    },
    "content": {
      "default": {
        "title": "title",
        "body": "body"
      }
    },
    "targetCount": 1048576,
    "timeToLive": 0,
    "sentTime": "2015-11-23T18:39:38.000+0900",
    "createdDateTime": "2015-11-23T18:39:38.000+0900",
    "messageStatus": "COMPLETE"
  }
}

"messageStatus"フィールドはメッセージの状態を表す。次のような状態がある。

READY：メッセージ送信リクエストが登録された状態。
IN_MQ：メッセージの作成が完了し、待機または送信中。
COMPLETE：メッセージの送信が完了した状態。
CANCEL_NO_TARGET：メッセージ送信対象が存在しないためキャンセルされた状態。次のような理由で送信がキャンセルされることがある。登録されたトークンがない時該当ChannelまたはUidがない時広告プッシュメッセージの場合、受信に同意したユーザーがいない時夜間広告プッシュメッセージ(21時～ 8時)の場合、夜間広告受信に同意したユーザーがいない時登録されたトークンが削除され、トークンがない時
CANCEL_INVALID_CERTIFICATE：証明書が無効でキャンセルされた状態。証明書の状態を確認する必要がある。
CANCEL_INVALID_MESSAGE：メッセージ形式が合っておらずキャンセルされた状態。
CANCEL_UNSUPPORTED_MESSAGE_TYPE：メッセージ形式が合っておらずキャンセルされた状態。
CANCEL_UNAUTHORIZED：証明書の認証プロセスで失敗した状態。証明書の状態を確認する必要がある。
CANCEL_UNKNOWN：内部エラーが発生した状態。

フィードバック

フィードバックの確認

[Method, URL]

GET https://api-push.cloud.toast.com/push/v1.3/appkey/{appkey}/feedback
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}

[Response Body]

{
    "feedback" : [{
        "uid" : "Uid",
        "token" : "Deleted Token",
        "newToken" : "New Token. Nullable",
        "pushType" : "GCM",
        "updateTime" : "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
    }],
    "header" : {
        "isSuccessful" : true or false,
        "resultCode": 0,
        "resultMessage" : "Success."
    }
}

文書修正履歴
- (2017.02.23)トークン照会API文書の補強

Notification > Push > API v1.3ガイド

APIテスト

Secret Key

Response

トークン

トークンの登録

トークン照会

a. トークンとプッシュタイプでトークン照会

b. uidでトークン照会

メッセージ

メッセージ送信

共通メッセージ

メッセージ照会

フィードバック

フィードバックの確認

目次