stats api

shotakowashi edited this page Mar 1, 2016 · 1 revision
Clone this wiki locally

収益化のための統計 API

Unity Ads では、パブリッシャーは収益化の、広告主はユーザー獲得の、統計データをそれぞれ CSV 形式で直接取得できる API を提供しています。この Unity Ads 統計 API を使うと、ゲームやキャンペーンのデータを取得して、定期的に提携レポートシステムに読み込ませることができます。実質、統計 API は Unity Ads 管理パネル で取得できるのと同じ統計ファイルを、自動的にフェッチするためのマシン間インターフェイスです。

概要

統計 API は 2 段階で動作します。まず、ユーザーが認証サーバーに対して GET リクエストを実行します。認証に成功すれば、サーバーは 302 HTTP リダイレクトメッセージで応答します。この応答には統計サーバーへの最終的な URL が含まれています

次に、ユーザーが署名済み URL に対して GET リクエストを実行すると、宛先サーバーはリクエストされたデータを CSV 形式でメッセージの本文に入れて返します。

Date,Country code,Country tier,adrequests,available,offers,started,views,revenue
2013-02-28 00:00:00, JP, 3, 0, 0, 0, 160242, 124254, 5678.91
2013-02-28 00:00:00, JP, 3, 0, 0, 0, 55124, 30517, 1234.56
2013-02-28 00:00:00, JP, 3, 0, 0, 0, 716582, 592829, 2345.67 
2013-02-28 00:00:00, JP, 3, 0, 0, 0, 84643, 77014, 3456.78
...

認証

Unity Ads 統計 API を使用するには、Unity Ads 管理パネル から API キーを取得する必要があります。API は "アカウント" の "ユーザーアカウント" 下部で確認できます。

この API キーを apikey HTTP GET パラメータへの認証リクエストに含めます。

認証に成功すれば、サーバーは 302 HTTP リダイレクトメッセージで応答します。この応答の Location HTTP ヘッダに、統計サーバーのデータへの URL が含まれています。実際のデータはこのリダイレクト URL から取得することになります。これは標準的な HTTP の動作であり、すべての HTTP クライアントでサポートされています。例えば

curl -L "http://gameads-admin.applifier.com/stats/monetization-api?apikey=APIKEY"

はファイルを直接コンソールに出力します。

統計サーバーは常に署名済み URL を要求し、有効な署名なしでアクセスされても動作しません。認証に失敗した場合、認証サーバーは HTTP/1.1 200 OK のヘッダで本文に次のようなエラーメッセージを入れて応答します。

{"error":"Authentication error","responseCode":500,"status":"error"}

リクエストフォーマット

収益化統計(あなたのゲームによるマネタイズの統計データを得る API)

収益化統計 API は以下のリクエストフォーマットをサポートしています。

http://gameads-admin.applifier.com/stats/monetization-api?apikey=<apikey>&fields=<fields>[&splitBy=<splitbyfields>][&scale=<scale>][&start=<startDate>][&end=<endDate>][&sourceIds=<sourceIds>]

where:

  • <apikey>Unity Ads 管理パネル から取得した API キーです。
  • <fields> には使用可能なフィールドのカンマ区切りリストが入ります。
    • adrequests – サーバに送られたキャンペーンクエリの数
    • available – どのくらいの回数在庫として表示されたか
    • offers – どのくらいの回数スクリーンに表示されたか
    • started – どのくらいの回数ユーザーが動画を再生開始したか
    • views – どのくらいの回数ユーザーが動画を完全視聴したか
    • revenue – いくらの収益になったか

デフォルトのフィールドセットは上記すべてが含まれています。

  • <splitbyfields> には、データを分割するディメンションのカンマ区切りリストが入ります。
    • source – データはソースゲームで分割されます
    • zone – データはゲームゾーンで分割されます
    • country – データはユーザーの国/地域別に分割されます

デフォルト設定は country です。データを一切分割したくない場合は splitBy=none と記述します。ターゲットとキャンペーンの両方で同時に分割することもできます。どちらも国での分割あり/なしの両方で使用可能です。

注意: 統計データを同時に複数のディメンションで分割すると、データサイズが飛躍的に増加します。その結果、処理時間が長くなりすぎてリクエストが失敗する場合があります。すべてのリクエストは、データ生成にかかる時間が 1 分を超える場合、60 秒で中止されます。

  • <scale> – データの時間単位1 日の区切りは UTC 00:00 時となります。時間単位として指定できる値は以下のとおりです。
    • all –(時間単位で区切らず、指定期間内の総計を出力する)
    • hour
    • day
    • week
    • month
    • quarter
    • year

デフォルトは day です。

  • <startDate> & <endDate> – データの開始時点と終了時点を指定します。受け付ける日付形式は以下のとおりです。
    • 負の数は現在を基準とした相対日付として扱います。例: -7 は 1 週間前を指します。
    • 日付文字列は ISO 形式で YYYY-MM-DDTHH:mm:SS:hhhZ としてください。 例: 2013-02-01T14:00:00.000Z

デフォルトでは開始日 -7、終了日 0 で、過去 1 週間のデータを取得します。

注意: 開始時点と終了時点が時間単位の区切りと一致しない場合、直前の区切りに修正されます。例えば、時間単位が 1 日の場合、上記の 14:00:00.000Z00:00:00.000Z に修正されます。

<sourceIds> – game id のカンマ区切りリストです。結果をフィルタするのに用います。デフォルトでは、デベロッパーのすべてのゲームが含まれます。

例:

注意: sourceIds パラメータをあなたのゲームIDと入れ替えるとそのゲームの統計情報、URLから sourceIds パラメータを取り除くと、あなたの全てのゲームの統計情報を得ることができます。

curl -L "http://gameads-admin.applifier.com/stats/monetization-api?apikey=c4ca4238a0b923820dcc509a6f75849bc81e728d9d4c2f636f067f89cc14862c&splitBy=zone,country&fields=adrequests,available,offers,views&start=2013-02-01T00:00:00.000Z&end=2013-03-01T00:00:00.000Z&scale=day&sourceIds=7162"