サポート (英語のみ)

キャンペーンAPIによるトリガー(クラシック)

概要

Nexthink EngageのAPIを使用すると、プログラムでキャンペーンをトリガーでき、セルフサービスポータルやチケットシステムなどのサードパーティ製品との統合が可能です。

前提条件

APIを経由してキャンペーンをトリガーするためには、次の事前条件が適用されます。

  • キャンペーンは手動でユーザーをターゲットにしています。

  • キャンペーンは公開されています。

  • キャンペーンは、プロファイルにキャンペーントリガーAPIへのアクセスのオプションが設定されているFinderアクセスを含むユーザーの代理でトリガーされます。

Engage APIの呼び出し

ポータルが、以下のURLでREST APIとしてEngage APIを公開しています。

https://[portal.company.com]/api/campaign/v1/trigger

URLでは、[portal.company.com]をポータルの外部DNS名に置き換えてください。

手動ターゲットキャンペーンをトリガーするには、APIのURLに対してJSONペイロードを含むPOSTリクエストを送信します（GETリクエストはサポートされておらず、404エラーを返します）。

名前
説明

CampaignUid

キャンペーンの識別子

UserSids

ユーザー識別子のリスト

Engage APIへのリクエストのJSONペイロード例。

\nEngage APIへの呼び出しはポータルに接続されたすべてのエンジンに配信され、非同期で実行されます。つまり、リクエストが検証された後にすぐにコールが返されます。 したがって、ポータルからの成功した応答は、選択されたユーザーがキャンペーン通知を受信したことを保証するものではありません。 失敗した応答の場合は、以下のエラー条件のリストを参照してください。

キャンペーンのUIDとユーザーのSIDを取得する

キャンペーンのUIDを取得するには：

  1. Engageキャンペーンを編集する権限を持つユーザーとしてFinderにログインします。

  2. 左側のメニューのCampaignsセクションから目的のキャンペーンを見つけます。

  3. キャンペーン名を右クリックします。

  4. Export > Campaign Uid to clipboardを選択します。

ユーザーのSIDを次の方法で見つけることができます。

  • Finder内のユーザーオブジェクトのSIDフィールドを表示します。

  • NXQLを使用してユーザーオブジェクトのsidフィールドを取得します。例：(select sid (from user))

  • GetSID API を呼び出します。

HTTPヘッダー

JSONコンテンツと基本認証を指定するために以下のHTTPヘッダーを使用してEngage APIにPOSTリクエストを送信します。

Content-type: application/json

Authorization: Basic [base-64(user:password)]

[base-64(user:password)]にはAPIアクセス権を持つNexthinkユーザーの資格情報（base-64エンコード）を置き換えてください。

エラー条件

リクエストに対する応答として、何か問題が発生した場合、ポータルは次のいずれかの回答を返す可能性があります。

エラータイプ
HTTPコード
原因

アクセス拒否

未承認 401

  • 認証エラー

禁止 403

  • 指定されたキャンペーンを実行するための権限が不十分なユーザー

バリデーションエラー

不正なリクエスト 400

  • 無効なJSON

  • 無効なエンコーディング

  • 無効なContent-type

  • 無効または不足しているキャンペーンのUID

  • 無効または不足しているユーザーのSID

  • 未知または未公開のキャンペーン

  • キャンペーンが手動でユーザーをターゲットにしていない

  • 指定されたユーザーのSIDが多すぎる（最大12,000ユーザー）

不明なエラー

内部サーバーエラー 500

  • 未定義の内部エラー

クワイエット期間

Engage APIを使用してキャンペーンをトリガーすることは、Finderから手動でトリガーすることと同等です。 そのため、API呼び出しによってキャンペーンをトリガーした後も、後のAPI呼び出しで同じユーザーに再度キャンペーンを送信できます。ユーザーが以前のキャンペーンに回答を拒否した場合も適用されます。

ただし、誤ってまたは繰り返しトリガーしてユーザーを困らせないように、Engage APIを使用してトリガーされたキャンペーンは、手動でトリガーされたキャンペーンと同じクワイエット期間を適用します：2時間。 この間、既にキャンペーンを受信したユーザーは再度同じキャンペーンを受信しません。

Engage APIへの呼び出しで、複数回キャンペーンがトリガーされる場合、ユーザーがオフラインの時にはキャンペーンは1回だけ受信されます。

関連するタスク

関連する参考文献

Last updated

Was this helpful?