광고 네트워크에 대한 클릭 서명

요약: 사기 책임을 방지하기 위해 클릭에 서명 유효성 검증을 추가하면 광고 네트워크에서 부정한 클릭이 발생하지 않습니다. 

클릭 서명 정보

간단한 기술을 이용하여, 사기범들은 광고 네트워크를 대신하여 클릭을 전송할 수 있고, 수천 또는 심지어 수백만의 가짜 클릭을 생성하여 앱스플라이어에 전송할 수 있습니다. 광고 네트워크 자체가 이 문제를 인식하지 못하는 경우도 있습니다. 

광고 네트워크가 실제로 앱스플라이어에 의해 어트리뷰트된 클릭이 가짜 클릭을 작성하는 사기범이 아니라 실제 광고 네트워크에서 클릭된 것인지 확인하기 위해, 광고 네트워크는 HMAC-SHA256 서명을 사용하여 클릭을 서명해야 합니다.

클릭 서명을 통해 클릭 도배로 인해 광고 네트워크의 트래픽이 차단되는 것을 방지합니다. 다시 말하면, 광고 네트워크가 대단히 많은 클릭 도배로 인해 클릭 차단 임계값에 도달하는 경우 앱스플라이어는 나머지 날짜에 대한 클릭 기록 및 어트리뷰션을 중지합니다.

서명을 통해 앱스플라이어는 클릭의 유효성을 검사하고 부정 행위자가 클릭 정보를 조작하지 않았는지 확인할 수 있습니다.

  • 검증된 클릭이 기록되고 광고 네트워크에 어트리뷰트됩니다. 
  • 검증되지 않은 클릭은 거부되며 
    • 광고 네트워크(광고주가 아님)용 Protect360 리포트에서 보실 수 있습니다. 더 알아보기
    • 전환율이나 광고 네트워크의 클릭 차단 임계값에 영향을 주지 않습니다.

클릭 서명 연동

흐름

다음 차트는 초기 개발 및 기본 테스트, 생산 테스트, 마지막으로 생산까지의 흐름을 개략적으로 설명합니다. 

Click_signing_integration_flow.png

절차

필수 구성 요소: 클릭 서명 API를 인증하기 위한 관리자의 API V2.0 토큰.

클릭 서명 방법:

  1. 비밀 키 생성 API로 비밀 키를 생성합니다.
    모범 사례: 유효 기간을 36시간으로 하고 24시간마다 새 비밀 키를 생성하여 사용합니다.
  2. 기밀 키 API 생성을 호출하는 서버의 코드 개발은 비밀 키를 사용하여 HMAC-SHA256 서명을 생성합니다. 코드 샘플을 참조하십시오.
    다음 표에 설명된 대로 기타 API를 사용할 수 있습니다.
  3. 상기 코드는 다음 정보를 클릭 URL에 추가합니다. 
    • Unix 타임스탬프(UTC로)를 포함하는 만기 파라미터이며, 이후 광고 네트워크에서 클릭을 요청하지 않습니다.
    • 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

 일러두기

클릭 서명이 생성되기 전에 링크에 특수 문자 또는 공백의 URL 인코딩이 발생하는지 확인하십시오. 서명을 먼저 생성하면 검증에 실패하게 됩니다.

클릭 서명 API

앱스플라이어는 광고 네트워크가 클릭 서명 프로세스를 관리하고 테스트하는 데 사용할 수 있는 API를 제공합니다. 아래 표의 API 목록과 API 사용에 필요한 정보가 포함된 섹션을 참조하십시오.

클릭 서명 API
API 메서드 설명
비밀 키를 생성합니다. 서명에 사용할 비밀 키를 생성합니다.
비밀 키를 취소합니다. 손상된 비밀 키를 취소합니다.
실험군 단일 클릭을 서명 테스트를 위해 전송합니다.
설정 모드

클릭 서명 모드의 설정 모드: 

  • 사용 안 함(기본값): 클릭 서명 유효성 검증이 수행되지 않았습니다.
  • 리포트 전용(테스팅 모드): 앱스플라이어는 클릭 서명을 검증하지만 서명이 잘못된 경우 클릭을 차단하지는 않습니다. 광고 네트워크는 포트 API를 사용하여 클릭 성공/실패에 대한 통계를 얻을 수 있습니다. 이를 통해 프로덕션 및 실제 트래픽에 영향을 주지 않고 클릭 서명을 테스트합니다.
  • 사용 가능: 앱스플라이어는 서명이 유효하지 않거나 누락되면 클릭을 차단합니다.
회로 차단기 설정

광고 네트워크에 너무 많은 차단 클릭이 들어오는 것을 보호하는 회로 차단기의 모드를 설정합니다.

  • 사용 가능(기본값): Protect360 시스템에서 너무 많은 클릭이 유효하지 않은 것으로 표시되는 경우 광고 네트워크에서 클릭이 잘못 차단되지 않도록 보호하려면 다음을 수행합니다.
    • 모드 API 변경 사항을 리포트 전용으로 설정합니다.
    • 그리고 클릭 서명 API가 올바르게 설정되어 있는지 확인하기 위한 이메일 알림이 광고 네트워크로 전송됩니다.
  • 사용 안 함: Protect360은 차단 비율이 비정상적으로 높은 경우에도 유효하지 않은 것으로 표시된 모든 클릭을 계속 차단합니다.
설정 가져오기

활성 비밀 키의 모드와 ID를 가져옵니다.

리포트

시스템이 리포트 전용 모드 또는 사용 가능 모드일 때 성공 클릭 및 실패 클릭에 대한 통계 가져오기. 이를 통해 프로덕션 및 실제 트래픽에 영향을 주지 않고 클릭 서명을 테스트합니다.

앱 제외 클릭 서명에서 제외할 앱 ID를 구성합니다. 
제외된 앱 삭제 앱 ID가 제외된 후 서명 클릭에 포함되도록 구성합니다.

비밀 키 메서드 생성

비밀 키 베이직 생성

카테고리 아이템

설명

요청 HTTP 메서드 POST
경로

https://hq1.appsflyer.com/api/p360-click-signing/secret?ttlHours=<ttlHours>

권한 관리 헤더 
응답 결과 비밀 키는 JSON 형식으로 반환됩니다.
  요청 제한 활성 비밀 키는 한 번에 최대 2개입니다.

API 요청

방법

POST https://hq1.appsflyer.com/api/p360-click-signing/secret?ttlHours=<ttlHours>
파라미터

파라미터

설명
ttlHours
  • 비밀 키를 사용할 수 있는 시간, 1-1440시간.
  • 기본값은 36시간입니다.

JSON 응답

설명

secret-key-id

비밀 키용 ID

secret key

클릭 서명을 위한 비밀 키

expiration

밀리초 단위의 에포크(Epoch) 시간

비밀 키 컬 예시와 응답을 생성합니다.

컬 요청


curl --location --request POST 'https://hq1.appsflyer.com/api/p360-click-signing/secret?ttlHours=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 응답 코드

응답 코드

코드 

메시지

설명

200 OK

 

401 승인되지 않음

유효하지 않거나 누락된 권한 관리 헤더

비밀 키 메서드 취소

비밀 키 베이직 취소합니다

카테고리 아이템

설명

요청 HTTP 메서드 DELETE
경로

https://hq1.appsflyer.com/api/p360-click-signing/secret/<secret-id>

권한 관리 헤더 
응답 결과 비어있음

API 요청

방법

DELETE https://hq1.appsflyer.com/api/p360-click-signing/secret/<secret-id>
파라미터

파라미터

설명
secret-id

취소할 비밀 키의 ID

비밀 키 컬 예시와 응답을 생성합니다.

컬 요청


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 응답 코드

응답 코드

코드 

메시지

설명

200 OK

 

401 승인되지 않음

유효하지 않거나 누락된 권한 관리 헤더

테스트 방법

테스트 기본

카테고리 아이템

설명

요청 HTTP 메서드 POST
경로

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

권한 관리 헤더 
응답 결과 JSON 형식으로 반환

API 요청

방법

POST https://hq1.appsflyer.com/api/p360-click-signing/test
파라미터

파라미터

설명
url

테스트할 클릭 URL(서명 포함)

JSON 응답

설명

test-status

통과 또는 실패함

message

테스트 실패 이유. 예시:

  • 서명 누락
  • 유효하지 않은 서명
  • 만료됨 

컬 예시 및 응답 테스트

컬 요청


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 응답 코드

응답 코드

코드 

메시지

설명

200 OK

 

401 승인되지 않음

유효하지 않거나 누락된 권한 관리 헤더

모드 메서드 설정

모드 베이직 설정합니다

카테고리 아이템

설명

요청 HTTP 메서드 POST
경로

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

옵션:

  • 사용 가능
    일러두기! 몇 시간 동안 리포트 전용 모드로 실행한 후에만 모드를 "사용 가능"으로 설정하고 모든 클릭이 서명 유효성 검사를 통과했는지 리포트를 확인하십시오.
  • disabled
  • report-only

모드 컬 예시 설정합니다

컬 요청


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 응답 코드

응답 코드

코드 

메시지

설명

200 OK

 

400 Bad request

유효하지 않은 모드

401 승인되지 않음

유효하지 않거나 누락된 권한 관리 헤더

회로 차단기 메서드 설정

회로 차단기 베이직 설정

카테고리 아이템

설명

요청 HTTP 메서드 POST
경로

https://hq1.appsflyer.com/p360-click-signing/config/circuit-breaker

권한 관리 헤더 
응답 결과 HTTP 상태

API 요청

방법

POST https://hq1.appsflyer.com/p360-click-signing/config/circuit-breaker
요청 본문 JSON

파라미터

설명
status
  • enabled
  • disabled

회로 차단기 컬 예시 및 응답 설정

컬 요청


curl --location --request POST 'https://hq1.appsflyer.com/api/p360-click-signing/config/circuit-breaker' \
-H 'Authorization: Bearer {API V2.0 token available to the admin in the dashboard.}'
--data-raw '{
"status":"enabled"
}'

HTTP 응답 코드

응답 코드

코드 

메시지

설명

200 OK

 

400 Bad request

유효하지 않은 상태

401 승인되지 않음

유효하지 않거나 누락된 권한 관리 헤더

설정 메서드 가져오기

설정 베이직 가져오기

카테고리 아이템

설명

요청 HTTP 메서드 GET
경로

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

권한 관리 헤더 
응답 결과 JSON 형식으로 반환

API 요청

방법

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

JSON 응답

설명

mode

다음 중 한 개:

  • enabled
  • disabled
  • report-only
circuit-breaker-config

다음 중 하나의 상태를 포함하는 JSON 개체:

  • enabled
  • disabled

active-key-ids

활성 키를 담고 있는 JSON 배열:

  • secret-key-id: 무작위로 생성한 비밀 키의 ID
  • 만료: 밀리초 단위의 비밀 키의 에포크 시간

excluded-app-ids

app-ids를 배제한 JSON 배열

설정 컬 예시 및 응답 가져오기

컬 요청


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 응답 코드

응답 코드

코드 

메시지

설명

200 OK

 

401 승인되지 않음

유효하지 않거나 누락된 권한 관리 헤더

리포트 메서드

리포트 베이직

카테고리 아이템

설명

요청 HTTP 메서드 GET
경로

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를 사용하려면 시작 날짜와 마감 날짜가 모두 필요하거나 둘 필요하지 않습니다. 시작/마감 날짜가 제공되지 않으면 리포트는 지난 24시간 동안의 결과를 표시합니다.

CSV 응답

컬럼 명

설명

시간

클릭의 날짜 및 시간. 형식: yyyy-mm-ddThh

total_clicks

리포트 기간 동안 총 클릭 수

valid_clicks

리포트 기간 동안 유효한 클릭 수

missing_signature

리포트 기간 동안 서명이 누락된 클릭 수

expired_clicks

리포트 기간 동안 만료된 클릭 수

invalid_signature

리포트 기간 동안 유효하게 서명한 클릭 수

no_active_secrets

시스템에 활성 비밀 키가 없기 때문에 거부된 클릭 수(일반적으로 시스템이 리포트 전용 모드인 경우)

컬 예시 및 응답 테스트

컬 요청


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 응답

시간

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 응답 코드

응답 코드

코드 

메시지

설명

200 OK

 

401 승인되지 않음

유효하지 않거나 누락된 권한 관리 헤더

앱 메서드 제외

앱 메서드 베이직 제외

카테고리 아이템

설명

요청 HTTP 메서드 POST
경로

https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/<app-id>

권한 관리 헤더 
응답 결과 비어있음

API 요청

방법

POST https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/<app-id>
파라미터

파라미터

설명
app-id

클릭 서명 유효성 검증에서 제외된 애플리케이션 ID

앱 컬 예시 제외

컬 요청


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 응답 코드

응답 코드

코드 

메시지

설명

200 OK

 

401 승인되지 않음

유효하지 않거나 누락된 권한 관리 헤더

제외된 앱 메서드 삭제

제외된 앱 메서드 베이직 삭제

카테고리 아이템

설명

요청 HTTP 메서드 DELETE
경로

https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/<app-id>

권한 관리 헤더 
응답 결과 비어있음

API 요청

방법

DELETE https://hq1.appsflyer.com/api/p360-click-signing/config/excluded-app/<app-id>
파라미터

파라미터

설명
app-id

클릭 서명 유효성 검증에서 제외된 앱 목록에서 제거할 애플리케이션 ID

제외된 앱 컬 예시 삭제

컬 요청


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 응답 코드

응답 코드

코드 

메시지

설명

200 OK

 

401 승인되지 않음

유효하지 않거나 누락된 권한 관리 헤더

코드 샘플

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;

추가 정보

문제 해결

앱스플라이어는 한 시간 동안 90% 이상의 클릭이 서명 유효성 검증에 실패하면 서명 유효성 검증을 중지하고 리포트 전용 모드로 돌아갑니다.

목적은 잠재적인 기술적 문제로부터 비즈니스를 보호하기 위한 것이며 이를 통해 다음과 같은 이상의 원인을 찾을 수 있습니다.

  • 서명이 예상대로 작동하고 클릭이 올바르게 차단되는 경우 회로 차단기 설정 방법을 사용하여 회로 차단기를 비활성화합니다.
  • 상기 클릭이 올바르게 차단되지 않은 경우:
    1. 설정 가져오기 방법을 사용하여 클릭 서명 설정을 검사하여 유효한 비밀 키가 있는지 확인합니다.
    2. 클릭 서명 리포트를 사용하여 차단된 클릭에 대한 자세한 정보를 얻고 잘못된 클릭의 출처(에이전시/앱- ID)와 이유를 조사합니다.
  • 비표준 연동으로 인해 특정 앱에서 문제가 발견되면 앱 제외 API를 사용하여 서명 유효성 검증을 클릭하지 않도록 이 앱을 제외합니다.
  • 설정에서 문제가 발견된 경우:
    1. 리포트 전용 모드에서 실행을 계속합니다.
    2. 사용자 쪽에서 클릭 서명 프로세스를 수정합니다.
    3. 클릭 서명 리포트에서 결과를 확인하고 클릭의 유효성을 예상대로 검증되는 경우 클릭 서명 유효성 검사를 다시 사용하도록 설정합니다.

자주 하는 질문

클릭 서명 FAQ

질문: 프로덕션에 영향을 주지 않고 어떻게 클릭 서명을 테스트합니까?

답변: 클릭 서명을 테스트하는 방법에는 두 가지가 있습니다.

  1. 테스트 API 사용. 이 방법은 개발 단계에서 단일 클릭 서명을 테스트하는 데 유용합니다.
  2. 리포트 전용 모드 사용. 리포트 전용 모드는 프로덕션 클릭에 대한 서명을 확인하고 차단할 항목을 표시하지만 잘못된 클릭을 차단하지는 않습니다. 따라서 실제 트래픽에 영향을 주지 않고 클릭 서명이 작동하는지 테스트할 수 있습니다.

질문: API 토큰과 비밀 키의 차이점은 무엇입니까?

답변: API 토큰: 클릭 서명 API를 인증하고 실행하기 위해 사용합니다. 광고 네트워크 당 한 개만 있습니다. 앱스플라이어 API V2.0 토큰은 관리자로부터 받아야 합니다.

보안 키: 서명 생성에 사용됩니다. 보안 키 생성 방법을 사용하여 보안 키를 생성합니다. 광고 네트워크는 새 보안 키를 생성하는 역할을 합니다. 특성 섹션을 참조하여 자세한 정보를 보십시오.

질문: 클릭 서명을 특정 캠페인에만 적용할 수 있나요?

답변: 아닙니다. 클릭 서명은 광고 네트워크에서 발생하는 모든 클릭에 적용됩니다. 클릭 서명에서 특정 앱을 제외할 수 있지만 특정 캠페인만 제외할 수는 없습니다.

특성

특성

항목

설명

클릭 서명 서명은 광고 네트워크 서버에 표시되어야 합니다.
비밀 키
  • 광고 네트워크에는 최대 두 개의 비밀 키가 동시에 활성화될 수 있습니다.
  • 각 비밀 키에는 만료 기간이 있습니다.
  • 만료된 비밀 키로 서명한 클릭은 거부됩니다.
리포트 API 클릭 유효성에 대한 업데이트된 통계는 매시간 집계됩니다.
도움이 되었습니까?