Webプッシュ通知サービス「Push7」の使い方や
活用方法をご提案します。

Push7 APIの利用

はじめに

Push7では、独自のWebAPIを提供しています。

これらを利用することにより、あなたのWebサイトやシステム上に、より柔軟な形でPush7を組み込むことが可能となります。

Push7のAPIは全てhttps://api.push7.jp/api/v1の下に提供されています。 そのため、例えばGET /foo/barという記述があった場合、GET https://api.push7.jp/api/v1/foo/barを意味します。 また、エンドポイント中に/api/v1というような記述がある場合は、/api/v1等の重複が無いということを意識して適宜読み替えてください。

なお、WebAPIのコールについては、他のAPIと同様に、エンドポイントに含まれるappnoは存在するappnoである必要があり、Authorizationヘッダに含まれるapikeyは妥当なapikeyである必要があります。

APIの共通仕様について

Push7 APIのrequest payloadおよびresponse bodyは全てJSON形式のデータあり、mime-typeapplication/jsonとしてやりとりされています。 また、正常系/異常系の基本的なresponseは以下となります。

認証について

Push7 APIは、一部認証を必要とするAPIが存在します。

認証が必要なAPIについては、HTTPヘッダーの「Authorization」ヘッダーに"Bearer: <apikey>"を付与するもしくは、APIのpayloadのapikeyにapikeyを付与することで認証が可能です。
なお、どちらか一方にて認証を行っている場合は、もう片方の設定は不要です。

POSTリクエストはどちらでも行うことが可能ですが、GETリクエストの場合はAuthorizationヘッダーを利用する方法でしか現状対応しておりませんので、可能な限りAuthorizationヘッダーを利用することを推奨します。

正常時のResponseについて

ステータスコードは全て200もしくは201として返却が行われます。
responseのフォーマットについては、それぞれのエンドポイントの仕様に依存します。

異常時のResponseについて

ステータスコードは400番台もしくは500番台での返却が行われます。 responseのフォーマットについては、基本的にJSON形式のデータが文字列として返却されます。

{
  "error": "error type"
}

なお、APIのコール時に503リクエストが発生した場合は、サーバー側は復帰してリトライ処理を行うことはありません。
503など、サーバーの負荷が原因のエラーが考えられる場合については、必ずクライアント側で再試行処理を行ってください。

アプリケーションの情報を取得するAPI

GET /$appno/head

このAPIは、ログインしていないユーザか、ログインしているがアプリケーションの所有者ではないユーザが叩くことができます。

Resource URL

appnoが3842942834ならば endpoint はhttps://api.push7.jp/api/v1/3842942834/headとなります。

Response

成功時、以下が返却されます。

{
    "alias": "push.push7.jp",
    "domain": "push.app.push7.jp",
    "icon": "https://dashboard.push7.jp/uploads/e1611ac7a1284618bf855309c8596ce6.png",
    "name": "push7",
    "subscribers": 15,
    "url": "https://push7.jp"
}

返却されるデータの説明は以下の通りです。

param description
name アプリケーションの名前()
url アプリケーションのURL
icon アプリケーションのアイコン画像のURL
domain アプリケーションの購読やservice-workerをインストールする為のページのドメイン名(アプリケーションドメイン)
alias アプリケーションのドメインエイリアス(作成されている場合,push.globalnet-ex.com 作成されていない時,null)
subscribers アプリケーションを購読しているユーザ数

Webプッシュ通知を送信するAPI

POST /$appno/send

Webプッシュ通知を作成するAPIです。このAPIを叩くには、appnoとapikeyが必要です。

これらの情報は、Push7のダッシュボード上の設定から入手することができます。 queryが指定された場合、条件を設定し、特定のパラメータを持つ購読者にだけWebプッシュ通知を送信することができます。

セグメント配信
なお、queryを用いて、特定の購読者に限定したWebプッシュ通知を配信するには、 Enterpriseプランのパラメータ配信オプションの契約が必要です。

前提条件

  • 既に今月送信しているPushの送信回数と今回送信しようとしているPushの送信回数の合計が、アプリケーションが所属しているプランのリミットに収まっている必要があります。
  • icon urlに&?=が含まれてはいけません。
  • icon urlのスキーマはhttpsである必要があります。

APIの呼び出しに必要なJSONデータ

以下のようなデータをpayloadとして必要とします。

{
  "title": "notification_title",
  "body": "notifaction_body",
  "icon": "https://push7.jp/notifycation_icon.png",
  "url": "http://push7.jp/",
  "apikey": "219182s390138",
  "disappear_instantly": true,
  "transmission_time": "2017/03/05 12:04"
  "query": {
    "mode": "OR",
    "params": [parameters]
  }
}

各データの説明は以下の通りです。

key required description
title true 通知時に表示されるタイトルです。
128文字まで受け付けます。
body true 通知時に表示される内容です。
512文字まで受け付けます。
icon true 通知時に表示されるアイコン画像のURLです。&?=が含まれてはいけません。 また、スキーマはhttpsである必要があります。
512文字まで受け付けます。
url true 通知クリック時に遷移するURLです。
512文字まで受け付けます。
 
apikey true アプリケーションのapikeyです。
disappear_instantly false 表示された通知がすぐ消えるか(秒数はUserAgent依存)どうかを設定できます。falseが指定された場合はユーザの通知クリックが必要です.defaultはtrueです。
transmission_time false 指定された日時までPush送信を遅延します %Y-%m-%d %H:%M 形式で指定して下さい。
query false パラメータのconditionです。この条件指定された購読グループに対してのみPush送信を行います。(パラメータベース配信) パラメータ管理も見て下さい。
query.mode false※1 パラメータの演算モードです。OR, AND, NOR, NANDから選択してください。
query.params false※1 通知先のパラメータを配列で指定してください。
個数は無制限、一つのパラメータ辺り128文字まで受け付けます。

※1: ただし、queryが存在している場合は必須です。

Response

成功時、以下が返却されます。

{
  "success": "created",
  "pushid": "23918391381239"
}

返却されるデータの説明は以下の通りです。

key description
pushid push通知のID