コンテンツにスキップ

HTTPイベントAPI

Zaraz HTTPイベントAPIを使用すると、Web APIを実行できない場所、たとえばサーバーやモバイルアプリからZarazに情報を送信できます。これは、ブラウザの外で発生しているイベント、たとえば成功したトランザクション、サインアップなどを追跡するのに便利です。このAPIは、複数のイベントをバッチで送信することも可能です。

APIエンドポイントの設定

APIは、エンドポイントを設定しない限り無効です。エンドポイントは、APIがアクセス可能なURLを決定します。たとえば、エンドポイントを/zaraz/apiに設定し、ドメインがexample.comの場合、APIへのリクエストはhttps://example.com/zaraz/apiに送信されます。

APIエンドポイントを有効にするには：

  1. Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
  2. Zaraz > Settingsに移動します。
  3. Endpoints > HTTP Events APIの下で、希望のパスを設定します。パスはドメインに対して相対的であり、/で始まる必要があります。

イベントの送信

設定したAPIエンドポイントは、JSONペイロードを持つPOSTリクエストを受け取ります。以下はペイロードの例です：

{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      }
    }
  ]
}

ペイロードにはevents配列が含まれている必要があります。この配列内の各Event Objectは、Zarazに処理させたい1つのイベントに対応します。上記の例は、Web APIを使用してzaraz.track('transaction successful', { value: "200" })を呼び出すのと似ています。

Event Objectはclientオブジェクトを保持しており、イベント自体に関する情報を渡すことができます。Event Objectに含めるすべてのキーは、ZarazダッシュボードのTrack Propertyとして利用可能になります。

予約された2つのキーがあります：

  • __zarazTrack: このキーの値はEvent Nameとして利用可能になります。これは通常、トリガーを構築する際の基準となります。上記の例では、これをtransaction successfulに設定することは、Web APIを使用するのときにzaraz.track("transaction successful")を呼び出すのと同じです。
  • __zarazEcommerce: このキーは、Zarazにイベントをeコマースイベントとして処理させたい場合にtrueに設定する必要があります。

systemキー

clientキーに加えて、systemキーを使用して、イベントが発生したデバイスに関する情報を含めることができます。たとえば、User-Agent文字列、クッキー、画面解像度を送信できます。Zarazは、異なるサードパーティツールに接続する際にこの情報を使用します。特定のフィールドに依存するツールもあるため、可能な限りすべての情報を含めることがしばしば有用です。

前述のペイロードにsystem情報を追加すると、以下の例のようになります：

{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      },
      "system": {
        "page": {
          "url": "https://example.com",
          "title": "My website"
        },
        "device": {
          "language": "en-US",
          "ip": "192.168.0.1"
        }
      }
    }
  ]
}

利用可能なすべてのシステムキーについては、以下の表を参照してください：

PropertyTypeDescription
system.cookiesObjectイベントに関連付けられたデバイスからのクッキーを保持するキーと値のオブジェクト。
system.device.ipStringイベントに関連付けられたデバイスのIPアドレス。
system.device.resolutionStringイベントに関連付けられたデバイスの画面解像度、WIDTHxHEIGHT形式。
system.device.viewportStringイベントに関連付けられたデバイスのビューポート、WIDTHxHEIGHT形式。
system.device.languageStringイベントに関連付けられたデバイスで使用される言語コード。
system.device.user-agentStringイベントに関連付けられたデバイスのUser-Agent文字列。
system.page.titleStringイベントに関連付けられたページのタイトル。
system.page.urlStringイベントに関連付けられたページのURL。
system.page.referrerStringイベントが発生した時点でのリファラーページのURL。
system.page.encodingStringイベントに関連付けられたページのエンコーディング。

APIレスポンスの処理

ペイロード内の各Event Objectに対して、ZarazはResult Objectで応答します。Result Objectsの順序は、Event Objectsの順序と一致します。

Zarazを使用して読み込んでいるツールによっては、APIからのレスポンスの本文に処理したい情報が含まれている場合があります。これは、一部のツールが完全なサーバーサイド実装を持たず、クッキー、クライアントサイドJavaScript、または類似のメカニズムに依存しているためです。各Result Objectには、以下の情報が含まれる場合があります：

| Result key | Description | | --- | --- | --- | | fetch | ツールがユーザーブラウザから送信したいFetchリクエスト。 | | execute | ツールがユーザーブラウザで実行したいJavaScriptコード。 | | return | ツールが返す情報。 | | cookies | ツールがユーザーに設定したいクッキー。 |

上記の情報を処理する必要はありませんが、一部のツールはこれに依存して正常に動作する場合があります。HTTPイベントAPIを使用し始める際に、上記の表の情報を処理せずに開始し、後で調整することができます。

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings