Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

HTTP Events API

最終更新 Markdown で表示Agent セットアップ

Zaraz の HTTP Events API を使うと、Web API を実行できない場所（サーバーやモバイルアプリなど）から Zaraz へ情報を送れます。ブラウザー外で起きるイベント（取引完了、サインアップなど）のトラッキングに向いています。API では、複数イベントをバッチで送ることもできます。

API エンドポイントを設定する

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

API エンドポイントを有効にするには、次の手順を行います。

  1. Cloudflare ダッシュボードで Settings ページを開きます。

    Settings を開く ↗

  2. 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" }) を呼ぶのと似ています。

イベントオブジェクトは client オブジェクトを持ち、イベント自体の情報を渡せます。イベントオブジェクトに含めたキーは、Zaraz ダッシュボードで Track Property として使えます。

予約済みのキーは次の 2 つです。

  • __zarazTrack: このキーの値は Event Name として使えます。通常、トリガーはこの値を基準に作ります。上の例で transaction successful に設定するのは、Web API を使い zaraz.track("transaction successful") を呼ぶのと同じです。
  • __zarazEcommerce: イベントを e コマースイベントとして Zaraz に処理させる場合、このキーを true に設定します。

system キー

client キーに加えて、system キーでイベント発生元デバイスの情報を含められます。たとえば User-Agent 文字列、Cookie、画面解像度を送れます。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"
        }
      }
    }
  ]
}

利用できる system キーは、次の表を参照してください。

プロパティ 型 説明
system.cookies Object イベントに関連するデバイスの Cookie を持つキーと値のオブジェクトです。
system.device.ip String イベントに関連するデバイスの IP アドレスです。
system.device.resolution String イベントに関連するデバイスの画面解像度です。形式は WIDTHxHEIGHT です。
system.device.viewport String イベントに関連するデバイスのビューポートです。形式は WIDTHxHEIGHT です。
system.device.language String イベントに関連するデバイスの言語コードです。
system.device.user-agent String イベントに関連するデバイスの User-Agent 文字列です。
system.page.title String イベントに関連するページのタイトルです。
system.page.url String イベントに関連するページの URL です。
system.page.referrer String イベント発生時点のリファラーページの URL です。
system.page.encoding String イベントに関連するページのエンコーディングです。

API レスポンスを処理する

ペイロード内の各イベントオブジェクトに対し、Zaraz は結果オブジェクト（Result Object）を返します。結果オブジェクトの順序は、イベントオブジェクトの順序と一致します。

Zaraz で読み込んでいるツールによっては、API レスポンスの本文に処理が必要な情報が含まれることがあります。一部のツールはサーバー側の実装が完全ではなく、Cookie、クライアント側 JavaScript、同様の仕組みにまだ依存するためです。各結果オブジェクトには、次の情報を含められます。

結果のキー 説明
fetch ツールがユーザーのブラウザーから送りたい Fetch リクエストです。
execute ツールがユーザーのブラウザーで実行したい JavaScript コードです。
return ツールが返す情報です。
cookies ツールがユーザーに設定したい Cookie です。

上の情報を処理する必要はありませんが、正しく動くために依存するツールもあります。まず上表の情報を処理せずに HTTP Events API を使い始め、必要に応じて後から対応できます。

役に立ちましたか？