APIリファレンス

パスの {content_type_id} には、コンテンツタイプのID、または、public_uidを指定してください。   例えば、blogというIDのコンテンツタイプ内で使われているタグ一覧を取得する場合、URLは以下のようにになります。

https://api.spearly.com/content_types/blog/contents/summary

https://api.spearly.com/content_types/blog/contents/c-content

対象のコンテンツタイプに属するコンテンツの一覧を取得する際に利用します。
パスの {content_type_id} には、コンテンツタイプのID、または、public_uidを指定してください。   例えば、blogというIDのコンテンツタイプのコンテンツ一覧を取得する場合、URLは以下のようにになります。

https://api.spearly.com/content_types/blog/contents

リクエストパラメータ

以下のリクエストパラメータを指定できます。いずれも任意のパラメータです。 

• limit
  • type: integer
  • デフォルト値: 10
  • 取得件数を制限します。
• offset
  • type: integer
  • デフォルト値: 0
  • 取得開始位置を指定します。
• order_direction
  • type: string
  • デフォルト値: 'desc'
  • descの場合はpublished_atの降順、ascの場合はpublished_atの昇順でソートします。order_byとの併用はできません。
• order_by
  • type: string
  • デフォルト値: -
  • latestに設定した場合は公開日時、popularに設定した場合は閲覧数の降順でソートします。閲覧数はそのコンテンツが取得された際にカウントされる値です。
• filter_by, filter_value
  • type: string
  • デフォルト値: -
  • 特定のフィールドと指定する値でコンテンツのリストをフィルタリングします。filter_by,filter_valueはセットで使います。filter_byでフィールドIDを指定して、filter_valueで値を指定します。部分一致で検索されます。
• filter_ref
  • type: string
  • デフォルト値: -
  • 参照コンテンツに対するフィルタリングです。filter_ref, filter_by, filter_valueを使って参照しているコンテンツを検索することができます。
• range_from
  • type: string
  • デフォルト値: -
  • range_fromに指定した日付よりも後に公開されたコンテンツを取得します。
• range_to
  • type: string
  • デフォルト値: -
  • range_toに指定した日付よりも以前に公開されたコンテンツを取得します。

ABテストを実行しているコンテンツのアクセス分析情報を登録する際に利用します。

このエンドポイントで、インプレッション、ユニークユーザ、セッション、コンバージョンの4つのデータを記録することができます。

リクエストパラメータ

送信するパラメータの例です。
nameでアクセス情報の種類を指定し、properties配下にコンテンツやパターン、ユーザとセッションを識別するためのIDなどの情報を設定します。

{
  "metric": {
    "name": "impressions",
    "properties": {
      "resource_type": "content",
      "resource_id": "content-alias",
      "pattern_name": "a",
      "value": 1,
      "distinct_id": "1234",
      "session_id": "5678",
      "session_id_expires_in": 1800
    }
  }
}

各パラメータの詳細を以下に説明します。

• metric.name
  • 必須
  • type: string
  • デフォルト値: なし
  • 設定できる値: impression, conversion
  • アクセス記録の種類を指定します。インプレッションの場合はimpression 、コンバージョンの場合はconversion を指定します。
• metric.propaties.resource_type
  • 必須
  • type: string
  • デフォルト値: なし
  • 設定できる値: content
  • 記録対象の種別を指定します。コンテンツのアクセス情報を記録する場合はcontent を指定してください。
• metric.propaties.resource_id
  • 必須
  • type: string
  • デフォルト値: なし
  • コンテンツのid、またはpublic_uidを指定します。これらの値はコンテンツ取得のAPIのレスポンスから取得できます。コンテンツエイリアスは使用できませんので、ご注意ください。
• metric.propaties.pattern_name
  • 必須
  • type: string
  • デフォルト値: なし
  • 設定できる値: a, b
  • パターンを指定します。a またはb を指定してください。
• metric.propaties.value
  • type: integer
  • デフォルト値: 1
  • カウンターに加算する値を指定します。デフォルトは1です。
• metric.propaties.distinct_id
  • 必須
  • type: string
  • デフォルト値: -
  • ユーザを識別するための文字列を設定します。Spearlyはdistinct_id を元に、このアクセスがどのユーザによるものなのかを判断します。 新しいdistinct_id と、metric.name にimpresions が指定されている場合、Spearlyは自動的にユニークユーザカウントに加算します。
    この値は可能な限り、ユーザごとに一意になるように実装する必要があります。後述するdistinct_idとsession_idの生成とCookieへの保存を参考に、値を生成、保持するようにしてください。
• metric.propaties.session_id
  • type: string
  • デフォルト値: -
  • セッションを識別するための文字列を設定します。Spearlyはsession_id を元に、このアクセスのセッションを判断します。 新しいsession_id と、metric.name にimpresions が指定されている場合、Spearlyは自動的にセッションカウントに加算します。
    session_idを設定しない場合、Spearlyはセッションの認識をせず、distinct_idを元にしたユニークユーザカウントと同じようにセッションカウントを行います。
    この値は、セッションごとに一意になるように実装する必要があります。後述するdistinct_idとsession_idの生成とCookieへの保存を参考に、値を生成、保持するようにしてください。
• metric.propaties.session_id_expires_in
  • type: integer
  • デフォルト値: -
  • セッションの保持時間を設定します。単位は秒です。ここに設定された時間、Spearlyはsession_id を保持します。ここで設定された時間を超えた場合、同一のセッションIDを指定しても、そのアクセスは新しいセッションとして処理されます。
    ここに設定する時間をアプリケーションやWebサイト側のsession_idの保持時間にも設定し、同一セッション中は同じsession_idが使われるように実装する必要があります。後述するdistinct_idとsession_idの生成とCookieへの保存を参考に実装してください。

distinct_idとsession_idの生成とCookieへの保存について

Spearlyのアクセス分析では、ユニークユーザ数、セッション数を記録することができます。アクセスがどのユーザ、どのセッションで行われたものなのかを判別するために、ユーザを識別するためのdistinct_id、セッションを識別するためのsession_idを、アプリケーションやWebサイト側で生成し、適切に保持する実装が必要です。

まず、distinct_idはユーザを識別するために使われるため、一度生成した後は可能な限り同じ値を保持する必要があります。
以下に、WebサイトにおけるCookieを用いたdistinct_idの生成と保持の実装例をご紹介します。

    getDistinctId: () => {
      const distinctId = document.cookie.replace(/(?:(?:^|.*;\s*)spearly_distinct_id\s*\=\s*([^;]*).*$)|^.*$/, "$1") || window.spearly.util.generateUUIDv4uuidv4();
      // Update distinct_id expires (default: 1 year)
      const distinctIdExpireDate = (new Date(Date.now() + 365 * 24 * 60 * 60 * 1000)).toUTCString();
      document.cookie = `spearly_distinct_id=${distinctId}; expires=${distinctIdExpireDate}; path=/;`;

      return distinctId;
    }

次に、セッションの識別に利用するsession_idについてです。セッションはコンテンツに到達してから、コンテンツを離脱するまでの一連の流れのことを指します。そのため、session_idはdistinct_idとは異なり、生成してからセッションを終了とする時間が経過した後は、保持すべきではありません。
以下に、WebサイトにおけるCookieを用いたsession_idの生成と保持の実装例をご紹介します。

    getSessionId: () => {
      const sessionExpire = 1800;
      const sessionId = document.cookie.replace(/(?:(?:^|.*;\s*)spearly_session_id\s*\=\s*([^;]*).*$)|^.*$/, "$1") || window.spearly.util.generateUUIDv4uuidv4();
      // Update session_id expires (default: 30 min)
      const sessionexpireDate = (new Date(Date.now() + sessionExpire * 1000)).toUTCString();
      document.cookie = `spearly_session_id=${sessionId}; expires=${sessionexpireDate};`;

      return sessionId
    }