オーディエンスAPI¶

オーディエンスAPIを使うと、任意のユーザーID のリストを使ってオーディエンスを作成、もしくは更新することができます。

自社の分析基盤や、他社サービスなどで作成したユーザーIDのリストをReproに登録し、マーケティング施策の配信対象として利用することができます。

注釈

Reproに登録されているユーザーが対象となります。Reproに登録されていないユーザーが含まれている場合は、対象として計上されません。

はじめに¶

Repro API トークンの確認¶

オーディエンスAPIを使うには、Repro API トークンを使用します。

設定 > プロジェクト設定 に行き、 プロジェクト > Repro API トークン を確認します。

単位時間あたりのアクセス上限¶

オーディエンスAPIには単位時間当たりのアクセス上限があります。

アクセス上限設定値は、10分あたり15件です。
リクエストが正常に完了すると、レスポンスの X-RateLimit-Limit ヘッダーに単位時間あたりのリクエスト上限回数が記載されます。
リクエスト数がアクセス上限数を超えると、 HTTP Status 429 (Too Many Requests) が返ります。

レスポンスヘッダーの詳細レスポンスヘッダーをご覧ください。

警告

アクセス上限設定値は予告なく変動する場合があります。

オーディエンスAPI v3¶

現在、オーディエンスAPI v3では下記の機能を提供しています。データをアップロードするために異なるエンドポイントに対して 2 回リクエストを送る必要があります。なお、2回目のリクエストについては、新規作成と更新で全く同じです。

機能	HTTPメソッド	エンドポイント
新規作成	`POST`	`https://api.reproio.com/v3/audiences`
更新	`PUT`	`https://api.reproio.com/v3/audiences/<オーディエンスID>`

以降では、リクエスト方法の詳細を記載していきます。

警告

エンドポイントのドメインが repro.io から reproio.com に変更されます。旧ドメインも引き続きご利用頂けますが、なるべく新しいドメインをご利用ください。

サンプルコード¶

オーディエンスの新規作成のサンプルコードを以下に記載します。オーディエンスの更新用に変更するには以下2点を変更してください。

1回目のリクエストのエンドポイントを更新用のものに変更する
1回目のリクエストメソッドを POST から PUT に変更する

#!/bin/bash

set -e

API_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AUDIENCES_URI=https://api.reproio.com/v3/audiences

file=$(realpath -e $1)
checksum=$(openssl dgst -md5 -binary ${file} | base64)
content_size=$(stat -c %s ${file})

body=$(cat <<EOF
{
  "name": "my-audience-api",
  "checksum":"${checksum}",
  "byte_size":"${content_size}"
}
EOF
)

# First request
response=$(curl -v -X POST \
                -H "X-Repro-Token: ${API_TOKEN}" \
                -H "Content-Type: application/json" \
                --data "${body}" \
                ${AUDIENCES_URI})
echo $response

# Get the value needed for the second request from the response
url=$(echo ${response} | jq -r .direct_upload.url)
content_type=$(echo ${response} | jq -r '.direct_upload.headers["Content-Type"]')
content_md5=$(echo ${response} | jq -r '.direct_upload.headers["Content-MD5"]')

# Second request
curl -X PUT \
    -H "Content-Type: ${content_type}" \
    -H "Content-MD5: ${content_md5}" \
    --upload-file ${file} \
    "${url}"

echo done

オーディエンスの新規作成¶

以下の2ステップを実行することで、オーディエンスの新規作成を行うことができます。

POST /v3/audiences を実行し、S3にダイレクトアップロードするためのpre-signed URLを取得する
PUT <pre-signed URL> を実行し、S3にファイルをアップロードする

1回目のリクエスト¶

エンドポイント¶

機能	HTTPメソッド	エンドポイント
新規作成	`POST`	`https://api.reproio.com/v3/audiences`

リクエストヘッダー¶

ヘッダー	説明	任意 / 必須
Content-Type	application/jsonを指定します。	必須
X-Repro-Token	Repro API トークンの確認で取得したトークンを指定します。	必須

リクエストパラメータ¶

フィールド	説明	任意 / 必須
name	作成するオーディエンスの名前。	必須
filename	ファイル名。オーディエンスの編集画面に表示されます。省略した場合は `source-from-api.csv` になります。	任意
checksum	ファイルのmd5 checksumをbase64エンコードしたもの。 `openssl dgst -md5 -binary hoge.csv \| base64` で算出することができます。	必須
byte_size	オーディエンスの作成・更新に利用するファイルのファイルサイズ	必須

ペイロード例¶

{
  "name": "audience name",
  "checksum": "J1h240z2CdsRjz2Et5mnkA==",
  "byte_size": "1024"
}

レスポンスヘッダー¶

レスポンスのヘッダーには、以下の値が含まれます。

ステータス	ヘッダー	説明
正常	`X-RateLimit-Limit`	単位時間あたりのアクセス上限
正常	`X-RateLimit-Remaining`	アクセスできる残り回数
正常	`X-RateLimit-Reset`	アクセス数がリセットされる時刻(unixtime)
リクエスト制限	`Retry-After`	再実行可能になるまでの秒数

正常系レスポンス¶

リクエスト成功時、レスポンスボディはJSON形式で以下の内容が返ってきます。

フィールド	説明
response.id	オーディエンスのID
response.name	オーディエンスの名前
response.direct_upload	2回目のリクエストに必要な情報を格納したオブジェクト
response.direct_upload.url	2回目のリクエストのエンドポイントURL
response.direct_upload.headers	2回目のリクエストに必要なヘッダー情報

正常系レスポンスボディ例¶

{
  "id": "ym6nnpkd",
  "direct_upload": {
    "url": "https://repro-direct-upload-production.s3.ap-northeast-1.amazonaws.com/Sx9367LtCmGDRdqfUJVjirRv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAITZGHBHURRYGMYHA%2F20200312%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20200312T062037Z&X-Amz-Expires=300&X-Amz-SignedHeaders=content-md5%3Bcontent-type%3Bhost&X-Amz-Signature=ef75a6b81944375822bcd4c2cdabf362bd02ccce5850577917b6b3fe087de0c5",
    "headers": {
      "Content-Type": "text/csv",
      "Content-MD5": "J1h240z2CdsRjz2Et5mnkA=="
    }
  },
  "name": "my-audience-api"
}

エラーレスポンス¶

レスポンスに含まれるステータスコードとエラーメッセージの一覧は下記になります。

400 Bad Request¶

リクエストにエラーがあります。エラーメッセージを確認の上、対応してください。

checksumに不正な文字列が含まれています。

レスポンスボディ:

{
  "error": {
    "messages": [
      "Validation failed: Checksum is invalid"
    ]
  }
}

byte_sizeが指定されていません。

レスポンスボディ:

{
  "error": {
    "messages": [
      "param is missing or the value is empty: byte_size"
    ]
  }
}

401 Unauthorized¶

Repro API トークンが指定されていません。

レスポンスボディ:

{
  "status": "unauthorized",
  "error": {
    "messages": [
      "Please include your Repro API Token as \"X-Repro-Token\" HTTP header."
    ]
  }
}

403 Forbidden¶

指定した Repro API トークンが間違っています。

レスポンスボディ:

{
  "status": "forbidden",
  "error": {
    "messages": [
      "Please check your Repro API Token as \"X-Repro-Token\" HTTP header."
    ]
  }
}

404 Not Found¶

エンドポイントが存在しません。

レスポンスボディ:

{
  "status": "not_found",
  "error": {
    "messages": [
      "Not found."
    ]
  }
}

429 Too Many Requests¶

リクエスト数が多すぎます。 Retry-After ヘッダーに記載された秒数待った後、リクエストを再開してください。

レスポンスボディ:

{
  "status": "too_many_requests",
  "error": {
    "messages": [
      "Too many requests hit the API too quickly."
    ]
  }
}

2回目のリクエスト¶

エンドポイント¶

HTTPメソッド	エンドポイント
`PUT`	1回目のリクエストが成功した場合、レスポンスに含まれる `response.direct_upload.url` の値

リクエストヘッダー¶

1回目のリクエストが成功した場合、レスポンスに含まれる response.direct_upload.headers の値全てをヘッダーとして指定してください。

リクエストパラメータ¶

オーディエンスを作成するためのCSVファイルをセットしてください。セット可能なファイルサイズの上限は500MBです。ファイルの形式は、1行に1つのユーザーIDを指定した以下のようなCSVです。例えば qwpeoifjadlskf, zxocjvasdfoiji, azxcpoqnadslpx のようなユーザーIDを設定している場合、次のような形式のファイルになります。

qwpeoifjadlskf
zxocjvasdfoiji
azxcpoqnadslpx
:

正常系レスポンス¶

オーディエンスの作成に成功したら、 200 のステータスコードが返されます。

エラーレスポンス¶

エラーレスポンスについてはこちらのドキュメントを参照してください。

インポート結果のメールを受信する¶

インポートが完了すると、下記のようなメールが送信されます。 URLにアクセスし、インポート結果を確認してください。

オーディエンスの更新¶

以下の2ステップを実行することで、オーディエンスの更新を行うことができます。

PUT /v3/audiences/<オーディエンスID> を実行し、S3にダイレクトアップロードするためのpre-signed URLを取得する
PUT <pre-signed URL> を実行し、S3にファイルをアップロードする

以降の手順はサンプルコードと同様になります。こちらを参照してください。エンドポイントについては、以下管理画面上のオーディエンス詳細画面から確認することもできます。

(廃止予定)オーディエンスAPI v2¶

警告

本API v2は 2021年8月31日に廃止予定です。 APIをご利用される場合はオーディエンスAPI v3 をご利用ください。

現在、オーディエンスAPI v2では下記の機能を提供しています。

機能	HTTPメソッド	エンドポイント
新規作成	`POST`	`https://api.reproio.com/v2/audiences`
更新	`PATCH`	`https://api.reproio.com/v2/audiences/<オーディエンスID>`

Repro API トークンの確認¶

オーディエンスAPIを使うには、Repro API トークンを使用する必要があります。

設定 > プロジェクト設定 に行き、 プロジェクト > Repro API トークン を確認します。

認証¶

取得した Repro API トークンをHTTPヘッダーの X-Repro-Token フィールドに設定してください。

単位時間あたりのアクセス上限¶

オーディエンスAPIには単位時間当たりのアクセス上限があります。

アクセス上限設定値は、10分あたり15件です。
リクエストが正常に完了すると、レスポンスの X-RateLimit-Limit ヘッダーに単位時間あたりのリクエスト上限回数が記載されます。
リクエスト数がアクセス上限数を超えると、 HTTP Status 429 (Too Many Requests) が返ります。

レスポンスヘッダーの詳細はオーディエンスAPIのレスポンスをご覧ください。

警告

アクセス上限設定値は予告なく変動する場合があります。

APIフォーマット¶

メッセージをHTTP bodyにJSONフォーマットでセットします。

name: オーディエンス名を指定します。作成時には必須、更新時には任意の項目となります。
user_ids: アプリやWebサイト内でユーザーID APIを使って登録されたユーザーのIDを配列形式で指定します。

オーディエンスの新規作成¶

オーディエンス新規作成APIはHTTPの POST メソッドを受けつけるエンドポイントと紐付いています。

POST https://api.reproio.com/v2/audiences

ペイロード例¶

{
  "name": "Audience created by API",
  "user_ids": [
    "user-123",
    "user-456",
    "user-789"
  ]
}

レスポンス例¶

オーディエンスの新規作成に成功したら、 201 Created のステータスコードと下記のようなレスポンスボディを持つレスポンスが返されます。

{
  "id": "xxxxxxxx",
  "name": "Audience created by API"
}

オーディエンスの更新¶

オーディエンス更新APIはHTTPの PATCH メソッドを受けつけるエンドポイントと紐付いています。

PATCH https://api.reproio.com/v2/audiences/xxxxxxxx

エンドポイントやRepro API トークンは管理画面のオーディエンスページからも確認できます。

ペイロード例¶

{
  "user_ids": [
    "modified-user-123",
    "modified-user-456",
    "modified-user-789"
  ]
}

レスポンス例¶

オーディエンスの更新に成功したら、 202 Accepted のステータスコードと下記のようなレスポンスボディを持つレスポンスが返されます。

{
  "id": "xxxxxxxx",
  "name": "Audience created by API"
}

オーディエンスAPIのリクエスト¶

リクエストヘッダー

リクエストのヘッダーには、以下の値を設定します。

ヘッダー	説明	必須
Content-Type	application/jsonを指定します。	必須
X-Repro-Token	Repro API トークンの確認で取得したトークンを指定します。	必須

リクエストボディ

メッセージをJSONフォーマットで設定します。

オーディエンスAPIのレスポンス¶

レスポンスヘッダー

レスポンスのヘッダーには、以下の値が含まれます。

ステータス	ヘッダー	説明
正常	`X-RateLimit-Limit`	単位時間あたりのアクセス上限
正常	`X-RateLimit-Remaining`	アクセスできる残り回数
正常	`X-RateLimit-Reset`	アクセス数がリセットされる時刻(unixtime)
リクエスト制限	`Retry-After`	再実行可能になるまでの秒数

レスポンスボディ

ユーザープロフィールAPIをコールした際の、レスポンスに含まれるステータスコードとエラーメッセージの一覧は下記になります。

400 Bad Request¶

リクエストにエラーがあります。エラーメッセージを確認の上、対応してください。

401 Unauthorized¶

Repro API トークンが指定されていません。

レスポンスボディ:

{
  "status": "unauthorized",
  "error": {
    "messages": [
      "Please include your Repro API Token as \"X-Repro-Token\" HTTP header."
    ]
  }
}

403 Forbidden¶

指定した Repro API トークンが間違っています。

レスポンスボディ:

{
  "status": "forbidden",
  "error": {
    "messages": [
      "Please check your Repro API Token as \"X-Repro-Token\" HTTP header."
    ]
  }
}

404 Not Found¶

エンドポイントが存在しません。

レスポンスボディ:

{
  "status": "not_found",
  "error": {
    "messages": [
      "Not found."
    ]
  }
}

429 Too Many Requests¶

リクエスト数が多すぎます。 Retry-After ヘッダーに記載された秒数待った後、リクエストを再開してください。

レスポンスボディ:

{
  "status": "too_many_requests",
  "error": {
    "messages": [
      "Too many requests hit the API too quickly."
    ]
  }
}