クリック署名：アドネットワーク向け

推奨
アドネットワーク
最終更新:

概要：クリックに署名の検証を追加することで、広告不正による被害を回避することが可能です。これにより、不正なクリックがアドネットワークに紐付けられなくなります。

クリック署名について

不正業者は、ごくわずかな技術でアドネットワークに代わって、数千はたまた数百万もの偽クリックを作成し、AppsFlyerへ送信することが可能です。アドネットワーク自身がこのような問題が発生していることを認識できていない場合もあります。

AppsFlyerによって媒体へ紐付けられたクリックが、不正業者によって作られた偽クリックではなく実際にアドネットワークから発生したものであることを確実にするために、HMAC-SHA256の署名を使ってクリックに署名を付与することをおすすめします。

また、クリック署名はクリック洪水によってアドネットワークの計測がブロックされるのを防ぐことにも役立つでしょう。アドネットワークが極端なレベルのクリック洪水によりブロックのしきい値に達してしまうと、AppsFlyerはクリックの記録と成果の紐付けを停止するからです。

この署名によりAppsFlyerはクリックを検証でき、クリック情報が不正業者によって操作されていないことを確認します。

  • 検証されたクリックは記録され、アドネットワークへ紐付けられます。
  • 無効になったクリックは除外され、以下のように処理されます：
    • アドネットワーク向け(広告主向けではなく)に提供されるProtect360のレポート画面に集計されます。
    • アドネットワークのコンバージョン率やクリック洪水のしきい値には影響を与えません。

クリック署名の連携

フロー

以下のチャートでは、初期の開発と基本テストから実稼働テスト、そして最終的な実稼働までの流れの概要を示しています。

Click_signing_integration_flow.png

手順

クリックに署名するには：

  1. シークレットキーの生成APIを使用して、シークレットキーを生成してください。
    推奨：24時間毎に新しいシークレットキーを生成して使用してください。シークレットキーの有効期限は36時間です。 
  2. シークレットキーの生成APIの呼び出し、受け取りとHMAC-SHA256の署名を作成するコードを、御社のサーバー内で開発してください。(コードサンプルも参照可能です。)
    以下の表に記載されている他のAPIも利用可能です。
  3. 以下のようにコードをクリックURLに追加してください： 
    • expiresのパラメータにはアドネットワークがクリックを主張しなくなるUnixのタイムスタンプを含めてください。
    • HMAC-SHA256の署名情報を含めてください。
    • 例： 

      https://app.appsflyer.com/com.app.id?pid=adnetwork_int&c=my_campaign&clickid=sdkfjasksjskdfj9845weh&af_site_id=12345      &expires=1597657118&signature=8fnDVzZP_WRZnv3KNJaREOEfvB5p9oRc_XlKEvUo8gk

クリック署名の各種API

AppsFlyerでは、アドネットワークがクリック署名のプロセルを管理できる各種APIを用意しています。以下表のAPI一覧と、APIの利用に必要な各種情報をまとめた各セクションを参照してください。 

クリック署名の各種API
APIメソッド 備考
Generate secret key 署名に使用するシークレットキーを生成します。
Revoke secret key シークレットキーを無効化します。
Test 署名をテストするために単発のクリックを送信します。
Configure mode

クリック署名の各モードを設定します： 

  • disabled (デフォルト設定): クリック署名の検証は行なわれません。
  • report-only (テストモード): AppsFlyerはクリック署名を検証しますが、無効な署名のクリックをブロックはしません。アドネットワークはReport APIを使ってクリックの成否に関する情報を取得可能です。
  • enabled: AppsFlyerが無効な署名を持つクリック、または署名が欠損しているクリックを実際にブロックします。
Get configuration

有効なシークレットキーのIDと選択されているモードを取得します。
Report

システムがreport-onlyモードまたはenabledモードの場合、正常なクリックと失敗したクリックに関する統計情報を取得します。
Exclude app クリック署名のルールから除外するアプリIDを設定します。
Remove excluded app 一度除外した後に、再度クリック署名のルールに含めるアプリIDを設定します。

Generate secret keyのメソッド

Generate secret keyの基本仕様

カテゴリ ポイント

説明
リクエスト HTTP method POST
Path

https://hq1.appsflyer.com/api/p360-click-signing/secret?ttl=<ttl>
認証ヘッダー 
レスポンス 結果 JSON内でシークレットキーが返されます。
  リクエスト制限 一度に最大2つまでシークレットキーをアクティブにできます

APIリクエスト

メソッド

POST https://hq1.appsflyer.com/api/p360-click-signing/secret?ttl=<ttl>
パラメーター

パラメーター

 説明
ttl
  • シークレットキーの有効期限(ttl)です。1時間から2160時間(90日)まで設定可能です。
  • デフォルト設定は36時間です。

JSONレスポンス

Key

説明
secret-key-id

シークレットキーのIDです。

secret key

クリック署名のシークレットキーです。

expiration

ミリ秒単位のエポックタイムです。

Generate secret keyのcurlサンプルとレスポンス

Curl リクエスト


curl --location --request POST 'https://hq1.appsflyer.com/api/p360-click-signing/secret?ttl=36' \
-H 'Authorization: Bearer {API V2.0 token available to the admin in the dashboard.}'

JSONレスポンス

{
	"secret-key-id": "59ad6547-affc-45eb-a6c9-9805f88ee755",
	"secret-key": "zGW6Rhrmb8+vuhHtL/Kp6rW5Ci9PNsjH1J5MGO9SIeg=",
	"expiration": 1610533263
}

HTTPのレスポンスコード

レスポンスコード

Code 

メッセージ

備考
200 OK

 
401 許可されていません

認証ヘッダーが無効、または見つかりません。

Revoke secret keyのメソッド

Revoke secret keyの基本仕様

カテゴリ ポイント

説明
リクエスト HTTP method 削除
Path

https://hq1.appsflyer.com/api/p360-click-signing/secret/<secret-id>
認証ヘッダー 
レスポンス 結果 Empty

APIリクエスト

メソッド

DELETE https://hq1.appsflyer.com/api/p360-click-signing/secret/<secret-id>
パラメーター

パラメーター

 説明
secret-id

無効にするシークレットキーのIDです。

Generate secret keyのcurlサンプルとレスポンス

Curl リクエスト


curl --location --request DELETE 'https://hq1.appsflyer.com/api/p360-click-signing/secret/59ad6547-affc-45eb-a6c9-9805f88ee755' \
-H 'Authorization: Bearer {API V2.0 token available to the admin in the dashboard.}'

HTTPのレスポンスコード

レスポンスコード

Code 

メッセージ

備考
200 OK

 
401 許可されていません

認証ヘッダーが無効、または見つかりません。

Testのメソッド

Testの基本仕様

カテゴリ ポイント

説明
リクエスト HTTP method POST
Path

https://hq1.appsflyer.com/api/p360-click-signing/test
認証ヘッダー 
レスポンス 結果 JSONで返されます。

APIリクエスト

メソッド

POST https://hq1.appsflyer.com/api/p360-click-signing/test
パラメーター

パラメーター

 説明
URL

署名を含む、テストで使用するクリックURLです。

JSONレスポンス

Key

説明
test-status

Passed(成功) もしくは Failed(失敗)

メッセージ

テストの失敗理由。例：

  • Missing signature (署名がありません。)
  • Invalid signature (署名が無効です。)
  • Expired  (署名が期限切れです。)

Testのcurlサンプルとレスポンス

Curl リクエスト


curl --location --request POST 'https://hq1.appsflyer.com/api/p360-click-signing/test' \
-H 'Authorization: Bearer {API V2.0 token available to the admin in the dashboard.}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "url": "https://app.appsflyer.com/com.app.id?pid=adnetwork_int&c=my_campaign&clickid=sdkfjasksjskdfj9845weh&af_site_id=12345&expires=1597657118&signature=8fnDVzZP_WRZnv3KNJaREOEfvB5p9oRc_XlKEvUo8gk"
}'

JSONレスポンス

{
	"test-status":"Passed / Failed",
	"message": "Invalid signature"
}

HTTPのレスポンスコード

レスポンスコード

Code 

メッセージ

備考
200 OK

 
401 許可されていません

認証ヘッダーが無効、または見つかりません。

Configure modeのメソッド

Configure modeの基本仕様

カテゴリ ポイント

説明
リクエスト HTTP method POST
Path

https://hq1.appsflyer.com/api/p360-click-signing/config/mode/<mode>
認証ヘッダー 
レスポンス 結果 JSONで返されます。

APIリクエスト

メソッド

POST https://hq1.appsflyer.com/api/p360-click-signing/config/mode/<mode>
パラメーター

パラメーター

 説明
mode

選択肢：

  • enabled
  • disabled
  • report-only

Configure modeのcurlサンプル

Curl リクエスト


curl --location --request POST 'https://hq1.appsflyer.com/api/p360-click-signing/config/mode/report-only' \
-H 'Authorization: Bearer {API V2.0 token available to the admin in the dashboard.}'

HTTPのレスポンスコード

レスポンスコード

Code 

メッセージ

備考
200 OK

 
400 Bad request

Invalid mode (無効なモード)
401 許可されていません

認証ヘッダーが無効、または見つかりません。

Get configurationのメソッド

Get configurationの基本仕様

カテゴリ ポイント

説明
リクエスト HTTP method GET
Path

https://hq1.appsflyer.com/api/p360-click-signing/config
認証ヘッダー 
レスポンス 結果 JSONで返されます。

APIリクエスト

メソッド

GET https://hq1.appsflyer.com/api/p360-click-signing/config

JSONレスポンス

Key

説明
mode

以下のいずれか：

  • enabled
  • disabled
  • report-only

active-key-ids

アクティブなキーを保持したJSON配列です:

  • secret-key-id: ランダムに生成されたシークレットキーのIDです。
  • expiration: シークレットキーのミリ秒単位のエポック時間で表現された有効期限です。

excluded-app-ids

除外したアプリIDを含むJSON配列です。

Get configurationのcurlサンプルとレスポンス

Curl リクエスト


curl --location --request GET 'https://hq1.appsflyer.com/api/p360-click-signing/config' \
-H 'Authorization: Bearer {API V2.0 token available to the admin in the dashboard.}'

JSONレスポンス

{
	"mode": "report-only",
	"active-key-ids": [
		{
			"secret-key-id": "59ad6547-affc-45eb-a6c9-9805f88ee755",
			"expiration": 1610533263
		}
	],
	"excluded-app-ids": [
		"app-id-1", 	"app-id-2"
	]

}

HTTPのレスポンスコード

レスポンスコード

Code 

メッセージ

備考
200 OK

 
401 許可されていません

認証ヘッダーが無効、または見つかりません。

Reportのメソッド

Reportの基本仕様

カテゴリ ポイント

説明
リクエスト HTTP method GET
Path

https://hq1.appsflyer.com/api/p360-click-signing/report
認証ヘッダー 
レスポンス 結果 CSVで返されます。

APIリクエスト

メソッド

GET https://hq1.appsflyer.com/api/p360-click-signing/report
パラメーター

パラメーター

 説明
start-date

レポートの開始日時です。形式： yyyy-mm-ddThh
end-date

レポートの終了日時です。形式： yyyy-mm-ddThh
API には、 start-dateとend-dateの両方を含めるか、もしくはどちらも入力しなくても機能します。start/end-dateが指定されていない場合、過去24時間の結果が表示されます。

CSVレスポンス

Column

説明
time

クリックの日時です。形式：yyyy-mm-ddThh

total_clicks

レポート期間におけるクリック数の合計です。

valid_clicks

レポート期間における有効なクリック数です。

missing_signature

レポート期間における署名が欠損しているクリック数です。

expired_clicks

レポート期間における署名の期限切れのクリック数です。

invalid_signature

レポート期間における無効な署名のクリック数です。

no_active_secrets

システム上に有効なシークレットキーがないために拒否されたクリック数です。(report-onlyモードの場合)

Testのcurlサンプルとレスポンス

Curl リクエスト


curl --location --request GET 'https://hq1.appsflyer.com/api/p360-click-signing/report?start-date=2021-01-07T07&end-date=2021-01-17T12' \
-H 'Authorization: Bearer {API V2.0 token available to the admin in the dashboard.}' \

CSVレスポンス

time

total_clicks

valid_clicks

missing_signature

expired_clicks

invalid_signature

no_active_signatures
2021-01-17T07

928082156

928082156

 0

 0

 0

 0

2021-01-17T08

923796132

923796132

 0

 0

 0

 0

2021-01-17T09

917541373

917541373

 0

 0

 0

 0

2021-01-17T10

909977064

909977064

 0

 0

 0

 0

2021-01-17T11

965104299

965104299

 0

 0

 0

 0

2021-01-17T12

975134824

975134824

 0

 0

 0

 0

HTTPのレスポンスコード

レスポンスコード

Code 

メッセージ

備考
200 OK

 
401 許可されていません

認証ヘッダーが無効、または見つかりません。

Exclude appのメソッド

Exclude appの基本仕様

カテゴリ ポイント

説明
リクエスト HTTP method POST
Path

https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/<app-id>
認証ヘッダー 
レスポンス 結果 Empty

APIリクエスト

メソッド

POST https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/<app-id>
パラメーター

パラメーター

 説明
app-id

クリック署名の検証対象から除外するアプリIDです。

Exclude appのcurlサンプル

Curl リクエスト


curl --location --request POST 'https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/appname.com' \
-H 'Authorization: Bearer {API V2.0 token available to the admin in the dashboard.}'

HTTPのレスポンスコード

レスポンスコード

Code 

メッセージ

備考
200 OK

 
401 許可されていません

認証ヘッダーが無効、または見つかりません。

Remove excluded appのメソッド

Remove excluded appの基本仕様

カテゴリ ポイント

説明
リクエスト HTTP method 削除
Path

https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/<app-id>
認証ヘッダー 
レスポンス 結果 Empty

APIリクエスト

メソッド

DELETE https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/<app-id>
パラメーター

パラメーター

 説明
app-id

クリック署名の検証対象から一度除外し、改めてそのリストから削除するアプリIDです。

Remove excluded appのcurlサンプル

Curl リクエスト


curl --location --request DELETE 'https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/appname.com' \
-H 'Authorization: Bearer {API V2.0 token available to the admin in the dashboard.}'

HTTPのレスポンスコード

レスポンスコード

Code 

メッセージ

備考
200 OK

 
401 許可されていません

認証ヘッダーが無効、または見つかりません。

Codeサンプル

package sign;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

.
.
.

String clickUrl = "https://app.appsflyer.com/com.app.id?pid=adnetwork_int&c=my_campaign&clickid=sdkfjasksjskdfj9845weh&af_site_id=12345";
String secretKey = "secret_key"; 
int ttlMinutes = 5;


//add expiration to the click URL
long expiration = System.currentTimeMillis() + (60000L * ttlMinutes);
clickUrl += "&expires="+expiration;

//create a SecretKey object from the given key string
SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(signingKey);

//generate a signature from the click url and encode it with base64 without padding
String generatedSignature =     
Base64.getUrlEncoder().withoutPadding().encodeToString(mac.doFinal(clickUrl.getBytes()));

//add the signature to the click URL
String signedClickUrl = clickUrl + "&signature=" + generatedSignature;

特性

特性

特性

説明
クリック署名 署名はアドネットワークのサーバー上で生成する必要があります。
シークレットキー
  • 広告ネットワークでは、最大2つまでシークレットキーを同時にアクティブにすることが可能です。
  • 個々のシークレットキーには有効期限があります。
  • 期限切れのシークレットキーで署名されたクリックは除外されます。
Report API クリックの有効性の更新は、時間単位で集計されます。