概要:クリックに署名の検証を追加することで、広告不正による被害を回避することが可能です。これにより、不正なクリックがアドネットワークに紐付けられなくなります。
クリック署名について
不正業者は、ごくわずかな技術でアドネットワークに代わって、数千はたまた数百万もの偽クリックを作成し、AppsFlyerへ送信することが可能です。アドネットワーク自身がこのような問題が発生していることを認識できていない場合もあります。
AppsFlyerによって媒体へ紐付けられたクリックが、不正業者によって作られた偽クリックではなく実際にアドネットワークから発生したものであることを確実にするために、HMAC-SHA256の署名を使ってクリックに署名を付与することをおすすめします。
また、クリック署名はクリック洪水によってアドネットワークの計測がブロックされるのを防ぐことにも役立つでしょう。アドネットワークが極端なレベルのクリック洪水によりブロックのしきい値に達してしまうと、AppsFlyerはクリックの記録と成果の紐付けを停止するからです。
この署名によりAppsFlyerはクリックを検証でき、クリック情報が不正業者によって操作されていないことを確認します。
- 検証されたクリックは記録され、アドネットワークへ紐付けられます。
-
無効になったクリックは除外され、以下のように処理されます:
- アドネットワーク向け(広告主向けではなく)に提供されるProtect360のレポート画面に集計されます。
- アドネットワークのコンバージョン率やクリック洪水のしきい値には影響を与えません。
クリック署名の連携
フロー
以下のチャートでは、初期の開発と基本テストから実稼働テスト、そして最終的な実稼働までの流れの概要を示しています。
手順
クリックに署名するには:
-
シークレットキーの生成APIを使用して、シークレットキーを生成してください。
推奨:24時間毎に新しいシークレットキーを生成して使用してください。シークレットキーの有効期限は36時間です。 -
シークレットキーの生成APIの呼び出し、受け取りとHMAC-SHA256の署名を作成するコードを、御社のサーバー内で開発してください。(コードサンプルも参照可能です。)
以下の表に記載されている他のAPIも利用可能です。 - 以下のようにコードをクリック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メソッド | 備考 |
---|---|
Generate secret key | 署名に使用するシークレットキーを生成します。 |
Revoke secret key | シークレットキーを無効化します。 |
Test | 署名をテストするために単発のクリックを送信します。 |
Configure mode |
クリック署名の各モードを設定します:
|
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 |
|
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(失敗) |
メッセージ |
テストの失敗理由。例:
|
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 |
選択肢:
|
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 |
以下のいずれか:
|
active-key-ids |
アクティブなキーを保持したJSON配列です:
|
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;
特性
特性 |
説明 |
---|---|
クリック署名 | 署名はアドネットワークのサーバー上で生成する必要があります。 |
シークレットキー |
|
Report API | クリックの有効性の更新は、時間単位で集計されます。 |