はじめに
このページでは、Push7 SDKで利用できるAPIについて詳しくご紹介します。
このページの内容は、Push7 SDKがWebページに導入されていることが前提となります。Push7 SDKの導入方法については、SDK導入のページを参考にしてください。
p7.init()
概要
Push7 SDKを初期化する関数です。主に
- appnoの設定
- mode, subscribeオプションの設定
を行います。
インターフェイス
p7.init('appno',{
mode:'native or normal',
subscribe: 'auto or manual',
lang: null
}).then(p7 => {});
初期化の終了時にPromiseを返します。
options
Key | 内容 | デフォルト | 備考 |
---|---|---|---|
appno | string | required | 使用するアプリケーションのappno |
mode | normal or native |
normal | Nativeの場合はswの設置が必須 |
subscribe | manual or auto |
auto |
Nativeモードにおける購読の方法。autoの場合は自動で, manualの場合は関数から購読する. Push7 Box を利用する場合は manual が必須 |
root | string | / |
Nativeモードをサブディレクトリで使用する場合に指定します。 |
lang | en or jp |
ブラウザ依存 | 言語設定 |
show_box_after | number | null | BOXにて購読が拒否された後、指定された日数が経過した時に再表示する. null の場合は 再表示しない。 |
subscribe_at | string, string[], HTMLElement, NodeList | null | 購読処理を特定のHTML要素までスクロールした際に実行します。NativeモードかつManual subscribeである必要があります。HTML Elementとそのリスト、CSSクエリとその配列で指定できます。UserAgent が iOS の場合、購読処理は発動せず何も起きません。 |
挙動について
init時に、次の処理が行われます。
- Buttonのタグの挿入
- BOXの表示(Dashboardで有効かつ、
subscribe:manual
の場合) - ServiceWorkerのインストール(
mode:native
の場合) - 購読処理(
mode:native
かつsubscribe:auto
の場合.p7.subscribe()
のコール)
Nativeモードを使用する
Nativeモードでは、購読ページを介すことなく直接サイト上からプッシュ通知を送ることが出来ます。native
オプションをtrue
に設定することでこのモードが有効になります。
ダッシュボードの導入設定
→Native設定
より必要なファイルをダウンロードし、サイトの直下に設置します。
サイトの直下に設置せず、サブディレクトリに設置したい場合は、root
オプションを指定します。
例えば、https://example.com/sub/
配下にファイルを設置したい場合、root
オプションに/sub/
を指定します。指定したディレクトリに、ダッシュボードからダウンロードしたファイルをそのまま配置してください。
特定の要素へのスクロールで購読する
mode:native
かつsubscribe:manual
の場合、ユーザーのスクロールをトリガーに購読処理(p7.subscribe()
と同等)を行うことができます。
この機能を利用するには、init
のオプションにsubscribe_at
を追加します。subscribe_at
には、1つまたは複数のCSSクエリ、そして1つまたは複数のHTMLElementを渡すことができます。
CSSクエリを利用する場合
CSSクエリをStringとして渡します。ユーザーがafter-content
というIDを持つ要素までスクロールした段階で購読ダイアログを表示したい場合、
p7.init({
appno: "<appno>",
mode: "native",
subscribe: "manual",
subscribe_at: "#after-content"
})
とします。
複数のCSSクエリを使用したい場合には、配列として渡すこともできます。after-content1
かafter-content2
をクラスに持つ要素のどちらかが表示された段階で購読ダイアログを表示したい場合、
p7.init({
appno: "<appno>",
mode: "native",
subscribe: "manual",
subscribe_at: [".after-content1", ".after-content2"]
})
とします。
HTMLElement, NodeListを利用する場合
HTMLElementやNodeListをsubscribe_atに指定することで特定の要素を指定できます。以下は、何らかのCSSクエリにマッチする要素をトリガーとして使う場合のサンプルです。
const elements = document.querySelectorAll("<some query>")
p7.init({
appno: "<appno>",
mode: "native",
subscribe: "manual",
subscribe_at: elements
})
p7.ready()
概要
Push7 SDKがp7.init
によって初期化されるまで待機します。
全てのSDKの処理は、この関数の後に行ってください。
インターフェイス
p7.ready().then(()=>{
// 初期化完了
p7.subscribe();
});
p7.subscribe()
概要
購読を行う関数です。
ボタン、BOXなどを含め、全ての購読処理はこの関数を通して実行されます。
インターフェイス
p7.ready().then(()=>p7.subscribe()).then();
Normalモードの挙動
mode:native
が指定されている場合、ページ内でServiceWorkerの購読処理を行います。
購読許諾に失敗した場合 文字列 permission_denied
で reject
します
Normalモードの挙動
mode:normal
の場合、購読ページを新しいwindowで開きます。
p7.unsubscribe()
概要
Nativeモードにおいて、購読解除を行うAPIです。NormalモードではPromiseがrejectされます。このAPIは、iOS ユーザー向けの 購読解除はできません。Push7 iOS アプリ経由で 解除する必要があります。
インターフェイス
p7.ready().unsubscribe().then();
ボタン
サイトの任意の場所に設置しユーザーがクリックすることで購読(p7.subscribe)が行われます。
吹き出しなし
<div class="p7button"></div>
吹き出し横
<div class="p7button" data-align="right"></div>
吹き出し上
<div class="p7button" data-align="top"></div>
カスタム文字
<div class="p7button" data-align="top" data-button-text="カスタムカスタム"></div>
BOX
ユーザーに購読を促すダイアログを表示します。基本的な設定はダッシュボード上の設定に依存します。
購読ボタンをクリックすると、p7.subscribe()
を実行します。
例外として
- mode:native
- subscribe:auto
- クライアントがiOS
の場合、直接ユーザーを購読ページに遷移させることは出来ないため、BOXをブラウザの購読許可ダイアログの代替として使用します。
Head API
アプリケーションの情報を取得します。
インターフェイス
p7.ready()
.then(()=>p7.get_head())
.then(head => console.log(head)); // -> {alias:null,appno:string,...}
return
次のプロパティを持つオブジェクトが返ります。
Key | 内容 |
---|---|
appno | initしたappno |
alias | 購読ページのエイリアス(存在する場合) |
domain | Push7の購読ページ |
icon | アプリケーションアイコン |
name | アプリケーション名 |
subscribers | 購読者数 |
url | アプリケーションURL |
パラメータ配信
概要
送信するユーザーをクエリすることができるパラメータ配信に関連するAPI群です。 なお、パラメータ配信ご利用にあたってはパラメータ配信オプションのご契約が必要となります。
現在、
p7.get_params()
現在のパラメータを照会するp7.add_params(string[])
パラメータを追加するp7.remove_params(string[])
パラメータを削除する
の3つのAPIが実装されています。
注意事項として、Normalモードにおけるパラメータの変更は再購読を行わないと反映されません。またセッションを超えた引き継ぎは行われません(リロードをすると消えます)。
p7.get_params():Promise<string[]>
現在のパラメータを照会します。
Nativeモードの場合は、実際にそのページで購読されているパラメータを表示します。
Normalモードの場合は、パラメータの引き継ぎは行われません。
p7.ready()
.then(() => p7.isSubscribed())
.then((isSubscribed) => {
if(isSubscribed) {
p7.get_params()
.then((params)=>{
console.log(params); // -> ['apple','orange']
})
}
})
p7.add_params(string[]):Promise<p7>
パラメータを追加します。
p7.ready()
.then(() => p7.isSubscribed())
.then((isSubscribed) => {
if(isSubscribed) {
p7.add_params(['apple','orange'])
.then((params)=>{
// パラメータが追加された
console.log(params); // ['pineapple','apple','orange']
})
}
})
p7.remove_params(string[]):Promise<p7>
追加済みのパラメータを削除します。
p7.ready()
.then(() => p7.isSubscribed())
.then((isSubscribed) => {
if(isSubscribed) {
p7.remove_params(['apple','orange'])
.then((params)=>{
// パラメータが削除された
console.log(params); // ['pineapple']
})
}
})
購読状態の取得
p7.isSubscribed():Promise<Boolean>
現在購読状態にあるかどうかを取得します。 非対応ブラウザの場合は強制的にfalseが返ります。
p7.ready().then(()=>{
p7.isSubscribed()
.then((isSubscribed)=>{
console.log(isSubscribed) // true or false
})
})
重複購読の確認・解消
p7.isDuplicated():Promise<Boolean>
現在のWebサイトでpush7-worker.jsが重複して登録されているかどうかを確認します。 もし重複していた場合はtrueが返ります。
p7.ready().then(()=>{
p7.isDuplicated()
.then((isDuplicated)=>{
console.log(isDuplicated) // true or false
})
})
p7. resetWorkers(string: root):Promise<Boolean>
Push7のService Workerの重複を解消します。
第一引数にrootを指定し、指定したroot以外のService Workerの登録を全て削除します。
例えば /sub1/
, /sub2/
, /sub3/
とあるときに、 /sub1/
を指定した場合、/sub2/
, /sub3/
が削除されます。
成功した場合にtrueが返ります。
rootにドメインルートを指定したい場合は、空もしくは'/'を指定してください。
p7.ready().then(()=>{
p7.isDuplicated()
.then((isDuplicated)=>{
if (!isDuplicated) return
p7.resetWorkers('/sub/')
.then((result)=>{
console.log(result) // true or false
})
})
})
バージョンの確認
p7.version
Push7 SDKのバージョンが確認できる変数です。
console.log(p7.version) // '2.7.0'