AdSelectionManager
public
class
AdSelectionManager
extends Object
java.lang.Object | |
↳ | android.adservices.adselection.AdSelectionManager |
AdSelection Manager는 앱 및 광고 SDK가 광고 선택 프로세스를 실행하고 노출수를 보고할 수 있는 API를 제공합니다.
요약
상속된 메서드 | |
---|---|
공개 메서드
get
public static AdSelectionManager get (Context context)
AdSelectionManager의 인스턴스를 생성하는 팩터리 메서드입니다.
매개변수 | |
---|---|
context |
Context : 사용할 Context 입니다. 이 값은 null 일 수 없습니다. |
반환 값 | |
---|---|
AdSelectionManager |
AdSelectionManager 인스턴스
이 값은 null 일 수 없습니다. |
getAdSelectionData
public void getAdSelectionData (GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)
기기에서 맞춤 잠재고객 데이터를 수집합니다. 압축 및 암호화된 blob을 반환하여 광고 선택을 위해 입찰 서버로 전송합니다. 자세한 내용은 입찰 서비스 설명 자료를 참조하세요.
맞춤 잠재고객 광고를 수집하려면 ad_render_id
이(가) 있어야 합니다.
이 API에서 생성된 blob을 사용하여 서버 측에서 실행된 광고 선택의 결과를 처리하는 방법은 AdSelectionManager#persistAdSelectionResult
를 참고하세요.
수신기에서 출력을 전달하고, 수신자는 성공적인 실행을 위해 GetAdSelectionDataOutcome
를 반환하거나, Exception
에 발생한 예외 유형과 이에 상응하는 오류 메시지가 포함됩니다.
IllegalArgumentException
이 발생하면 API가 광고 선택을 실행하기 위해 수신한 잘못된 입력 인수로 인해 발생합니다.
'AdSelection Services 실패' 오류 메시지와 함께 IllegalStateException
이 발생하면 광고 선택 서비스의 내부 실패로 인해 발생합니다.
TimeoutException
이 발생하면 입찰, 점수 산정 또는 낙찰된 광고를 찾기 위한 전반적인 선택 프로세스 중에 시간 초과가 발생하면 발생합니다.
LimitExceededException
이 발생하는 경우 호출 패키지가 허용 비율 제한을 초과하여 제한될 때 발생합니다.
SecurityException
이 발생하는 경우 호출자가 승인되지 않았거나 권한이 요청되지 않았을 때 발생합니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
필요
매개변수 | |
---|---|
request |
GetAdSelectionDataRequest : 이 값은 null 일 수 없습니다. |
executor |
Executor : 이 값은 null 일 수 없습니다.
콜백 및 리스너 이벤트가 이 Executor 를 통해 전달되므로 사용되는 스레드를 쉽게 제어할 수 있습니다. 애플리케이션의 기본 스레드를 통해 이벤트를 전달하려면 Context.getMainExecutor() 를 사용하면 됩니다.
그 외의 경우에는 적절한 스레드에 전달되는 Executor 를 제공합니다. |
receiver |
OutcomeReceiver : 이 값은 null 일 수 없습니다. |
getTestAdSelectionManager
public TestAdSelectionManager getTestAdSelectionManager ()
반환 값 | |
---|---|
TestAdSelectionManager |
이 값은 null 일 수 없습니다. |
PersistentAdSelectionResult
public void persistAdSelectionResult (PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
서버 측의 광고 선택 결과를 유지합니다. 자세한 내용은 입찰 서비스 설명 자료를 참조하세요.
암호화된 blob을 생성하여 서버 측에서 광고 선택을 실행하는 방법은 AdSelectionManager#getAdSelectionData
를 참고하세요.
수신기에서 출력을 전달하고, 수신자는 성공적인 실행을 위해 AdSelectionOutcome
를 반환하거나 Exception
에 발생한 예외 유형과 이에 상응하는 오류 메시지가 포함됩니다.
IllegalArgumentException
이 발생하면 API가 광고 선택을 실행하기 위해 수신한 잘못된 입력 인수로 인해 발생합니다.
'AdSelection Services 실패' 오류 메시지와 함께 IllegalStateException
이 발생하면 광고 선택 서비스의 내부 실패로 인해 발생합니다.
TimeoutException
이 발생하면 입찰, 점수 산정 또는 낙찰된 광고를 찾기 위한 전반적인 선택 프로세스 중에 시간 초과가 발생하면 발생합니다.
LimitExceededException
이 발생하는 경우 호출 패키지가 허용 비율 제한을 초과하여 제한될 때 발생합니다.
SecurityException
이 발생하는 경우 호출자가 승인되지 않았거나 권한이 요청되지 않았을 때 발생합니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
필요
매개변수 | |
---|---|
request |
PersistAdSelectionResultRequest : 이 값은 null 일 수 없습니다. |
executor |
Executor : 이 값은 null 일 수 없습니다.
콜백 및 리스너 이벤트가 이 Executor 를 통해 전달되므로 사용되는 스레드를 쉽게 제어할 수 있습니다. 애플리케이션의 기본 스레드를 통해 이벤트를 전달하려면 Context.getMainExecutor() 를 사용하면 됩니다.
그 외의 경우에는 적절한 스레드에 전달되는 Executor 를 제공합니다. |
receiver |
OutcomeReceiver : 이 값은 null 일 수 없습니다. |
보고서 이벤트
public void reportEvent (ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)
adSelectionId
로 식별된 광고 선택 실행에서 선택한 광고에 관해 보고할 새 광고 이벤트가 있음을 서비스에 알립니다. 광고 이벤트는 지정된 adSelectionId
에 연결된 광고에서 발생하는 모든 상황을 의미합니다. 광고 이벤트가
보고되는 시점은 보장되지 않습니다. 이벤트 보고가 지연될 수 있고 보고서는 일괄 처리될 수 있습니다.
서비스는 ReportEventRequest#getKey()
를 사용하여 registerAdBeacon
에 등록된 reportingUri
를 가져옵니다. registerAdBeacon
에 관한 자세한 내용은 reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver)
문서를 참고하세요. 그런 다음 서비스는 ReportEventRequest#getData()
를 POST 요청의 요청 본문에 연결하고 요청을 전송합니다. POST 요청 본문에 text/plain
의 content-type
가 포함되고 데이터는 charset=UTF-8
로 전송됩니다.
수신기에서 출력을 전달하여 성공적인 실행을 위해 빈 Object
를 반환하거나 Exception
에 발생한 예외 유형과 이에 상응하는 오류 메시지가 포함됩니다.
IllegalArgumentException
이 발생하는 경우 API가 광고 이벤트를 보고하기 위해 수신한 잘못된 입력 인수로 인해 발생합니다.
'AdSelection Services 실패' 오류 메시지와 함께 IllegalStateException
이 발생하면 광고 선택 서비스의 내부 실패로 인해 발생합니다.
LimitExceededException
이 발생하는 경우 호출 패키지가 허용 비율 제한을 초과하여 제한될 때 발생합니다.
SecurityException
이 발생하는 경우 호출자가 승인되지 않았거나 권한이 요청되지 않았을 때 발생합니다.
이벤트는 최선의 시도로 최대 한 번 보고됩니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
필요
매개변수 | |
---|---|
request |
ReportEventRequest : 이 값은 null 일 수 없습니다. |
executor |
Executor : 이 값은 null 일 수 없습니다. |
receiver |
OutcomeReceiver : 이 값은 null 일 수 없습니다. |
reportImpression 보고서
public void reportImpression (ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)
adSelectionId
로 식별된 광고 선택 실행에서 선택한 광고에 관해 보고할 새 노출이 있음을 서비스에 알립니다. 노출이 보고되는 시점은 보장되지 않습니다. 노출 보고가 지연될 수 있고 보고서는 일괄 처리될 수 있습니다.
낙찰된 판매자 보고 URL을 계산하기 위해 서비스는 ReportImpressionRequest.getAdSelectionConfig()
에 있는 AdSelectionConfig#getDecisionLogicUri()
에서 판매자의 JavaScript 로직을 가져옵니다. 그런 다음 서비스는 판매자 JS에서 찾은 reportResult
함수 중 하나를 실행하여 기기 내 신호와 ReportImpressionRequest#getAdSelectionConfig()
를 입력 매개변수로 제공합니다.
reportResult
의 함수 정의는 다음과 같습니다.
function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
return { 'status': status, 'results': {'signals_for_buyer': signals_for_buyer,
'reporting_url': reporting_url } }; }
낙찰된 구매자 보고 URL을 계산하기 위해 서비스는 낙찰된 구매자의 JavaScript 로직을 가져옵니다. 이 로직은 구매자의 CustomAudience.getBiddingLogicUri()
를 통해 가져옵니다. 그런 다음 서비스는 구매자 JS에서 발견된 reportWin
함수 중 하나를 실행하여 기기 내 신호, reportResult
로 계산된 signals_for_buyer
, ReportImpressionRequest#getAdSelectionConfig()
의 특정 필드를 입력 매개변수로 제공합니다.
reportWin
의 함수 정의는 다음과 같습니다.
function reportWin(ad_selection_signals, per_buyer_signals, signals_for_buyer,
contextual_signals, custom_audience_reporting_signals) { return {'status': 0, 'results':
{'reporting_url': reporting_url } }; }
또한 구매자와 판매자가 특정 광고 이벤트에 대한 보고서를 수신하도록 등록할 수 있습니다. 이렇게 하려면 구매자와 판매자의 reportWin
및 reportResult
내에서 각각 플랫폼 제공 registerAdBeacon
함수를 호출하면 됩니다.
registerBeacon
의 함수 정의는 다음과 같습니다.
function registerAdBeacon(beacons)
. 여기서 beacons
는 문자열-문자열 쌍으로 구성된 사전입니다.
구매자/판매자가 보고서에 관심을 보이는 각 광고 이벤트의 경우 beacons
사전에 event_key
: event_reporting_uri
쌍을 추가합니다. 여기서 event_key
는 특정 이벤트의 식별자입니다. 이 event_key
는 SDK가 reportEvent(ReportEventRequest, Executor, OutcomeReceiver)
를 호출할 때 ReportEventRequest#getKey()
와 일치해야 합니다. 또한 각 event_reporting_uri
는 Uri
로 올바르게 파싱되어야 합니다. SDK가 reportEvent(ReportEventRequest, Executor, OutcomeReceiver)
를 호출할 때 보고되는 Uri
입니다.
구매자/판매자가 이벤트를 수신하려는 모든 페어링을 추가하면 registerAdBeacon(beacons)
를 호출할 수 있습니다. 여기서 beacons
은 쌍을 추가한 사전의 이름입니다.
다음과 같은 상황에서 registerAdBeacon
이 TypeError
을 발생시킵니다.
registerAdBeacon
가 두 번 이상 호출됩니다. 이 오류가 reportWin/reportResult에서 발견되면 원래 쌍이 등록됩니다.registerAdBeacon
에는 정확히 1개의 사전 인수가 없습니다.- 1 dict 인수의 콘텐츠는 모든
String: String
쌍이 아닙니다.
출력은 receiver
에 의해 전달되어 성공적인 실행을 위해 빈 Object
를 반환하거나 Exception
에 발생한 예외 유형과 이에 상응하는 오류 메시지가 포함됩니다.
IllegalArgumentException
이 발생하는 경우 이 문제는 API가 노출을 보고하기 위해 수신한 잘못된 입력 인수로 인해 발생합니다.
'AdSelection Services 실패' 오류 메시지와 함께 IllegalStateException
이 발생하면 광고 선택 서비스의 내부 실패로 인해 발생합니다.
LimitExceededException
이 발생하는 경우 호출 패키지가 허용 비율 제한을 초과하여 제한될 때 발생합니다.
SecurityException
이 발생하는 경우 호출자가 승인되지 않았거나 권한이 요청되지 않았을 때 발생합니다.
노출은 최선의 시도로 최대 한 번 보고됩니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
필요
매개변수 | |
---|---|
request |
ReportImpressionRequest : 이 값은 null 일 수 없습니다. |
executor |
Executor : 이 값은 null 일 수 없습니다. |
receiver |
OutcomeReceiver : 이 값은 null 일 수 없습니다. |
selectAds
public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
이전에 실행한 광고 선택의 결과에서 광고를 선택합니다.
입력 adSelectionFromOutcomesConfig
는 Ads SDK에서 제공하고 AdSelectionFromOutcomesConfig
객체는 바인더 호출을 통해 전송됩니다. 따라서 이러한 객체의 총 크기에는 Android IPC 제한이 적용됩니다. AdSelectionFromOutcomesConfig
를 전송하지 못하면 TransactionTooLargeException
이 발생합니다.
수신기에서 출력을 전달하고, 수신자는 성공적인 실행을 위해 AdSelectionOutcome
를 반환하거나 Exception
에 발생한 예외 유형과 이에 상응하는 오류 메시지가 포함됩니다.
입력 adSelectionFromOutcomesConfig
에는 다음이 포함됩니다.
Seller
은(는) 등록된AdTechIdentifier
이어야 합니다. 그렇지 않으면IllegalStateException
이 발생합니다.List of ad selection ids
가 있어야 하며 동일한 애플리케이션에서 시작된selectAds(AdSelectionConfig, Executor, OutcomeReceiver)
호출에서 가져와야 합니다. 그러지 않으면 입력 유효성 검사를 위한IllegalArgumentException
에서 광고 선택 ID를 위반하는 등록정보를 발생시킵니다.- HTTPS 또는 광고 선택 사전 빌드된 스키마를 따를 수 있는
Selection logic URI
입니다.URI가 HTTPS 스키마를 따르는 경우 호스트는
seller
와 일치해야 합니다. 그렇지 않으면IllegalArgumentException
이 발생합니다.사전 빌드된 URI는
selectOutcome
의 필수 JavaScript를 일반적인 사전 빌드된 로직을 대체하는 방법입니다. 이 엔드포인트의 사전 빌드된 URI는 다음과 같아야 합니다.ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>
지원되지 않는 사전 빌드된 URI가 전달되거나 사전 빌드된 URI 기능이 서비스에 의해 사용 중지되면
IllegalArgumentException
이 발생합니다.지원되는
<name>
및 필수<script-generation-parameters>
는AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri
를 참조하세요.
IllegalArgumentException
이 발생하면 API가 광고 선택을 실행하기 위해 수신한 잘못된 입력 인수로 인해 발생합니다.
'AdSelection Services 실패' 오류 메시지와 함께 IllegalStateException
이 발생하면 광고 선택 서비스의 내부 실패로 인해 발생합니다.
TimeoutException
이 발생하면 입찰, 점수 산정 또는 낙찰된 광고를 찾기 위한 전반적인 선택 프로세스 중에 시간 초과가 발생하면 발생합니다.
LimitExceededException
이 발생하는 경우 호출 패키지가 허용 비율 제한을 초과하여 제한될 때 발생합니다.
SecurityException
이 발생하는 경우 호출자가 승인되지 않았거나 권한이 요청되지 않았을 때 발생합니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
필요
매개변수 | |
---|---|
adSelectionFromOutcomesConfig |
AdSelectionFromOutcomesConfig : 이 값은 null 일 수 없습니다. |
executor |
Executor : 이 값은 null 일 수 없습니다.
콜백 및 리스너 이벤트가 이 Executor 를 통해 전달되므로 사용되는 스레드를 쉽게 제어할 수 있습니다. 애플리케이션의 기본 스레드를 통해 이벤트를 전달하려면 Context.getMainExecutor() 를 사용하면 됩니다.
그 외의 경우에는 적절한 스레드에 전달되는 Executor 를 제공합니다. |
receiver |
OutcomeReceiver : 이 값은 null 일 수 없습니다. |
selectAds
public void selectAds (AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
기기에서 광고 선택 프로세스를 실행하여 호출자 애플리케이션의 리마케팅 광고를 선택합니다.
입력 adSelectionConfig
는 Ads SDK에서 제공하고 AdSelectionConfig
객체는 바인더 호출을 통해 전송됩니다. 따라서 이러한 객체의 총 크기에는 Android IPC 제한이 적용됩니다. AdSelectionConfig
를 전송하지 못하면 TransactionTooLargeException
이 발생합니다.
입력 adSelectionConfig
에는 HTTPS 또는 광고 선택 사전 빌드된 스키마를 따를 수 있는 Decision Logic Uri
가 포함되어 있습니다.
URI가 HTTPS 스키마를 따르는 경우 호스트는 seller
와 일치해야 합니다. 그렇지 않으면 IllegalArgumentException
이 발생합니다.
사전 빌드된 URI는 scoreAds
의 필수 JavaScript를 일반적인 사전 빌드된 로직을 대체하는 방법입니다. 이 엔드포인트의 사전 빌드된 URI는 다음과 같아야 합니다.
ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>
지원되지 않는 사전 빌드된 URI가 전달되거나 사전 빌드된 URI 기능이 서비스에 의해 사용 중지되면 IllegalArgumentException
이 발생합니다.
지원되는 <name>
및 필수 <script-generation-parameters>
는 AdSelectionConfig.Builder#setDecisionLogicUri
를 참조하세요.
수신기에서 출력을 전달하고, 수신자는 성공적인 실행을 위해 AdSelectionOutcome
를 반환하거나 Exception
에 발생한 예외 유형과 이에 상응하는 오류 메시지가 포함됩니다.
IllegalArgumentException
이 발생하면 API가 광고 선택을 실행하기 위해 수신한 잘못된 입력 인수로 인해 발생합니다.
'AdSelection Services 실패' 오류 메시지와 함께 IllegalStateException
이 발생하면 광고 선택 서비스의 내부 실패로 인해 발생합니다.
TimeoutException
이 발생하면 입찰, 점수 산정 또는 낙찰된 광고를 찾기 위한 전반적인 선택 프로세스 중에 시간 초과가 발생하면 발생합니다.
LimitExceededException
이 발생하는 경우 호출 패키지가 허용 비율 제한을 초과하여 제한될 때 발생합니다.
SecurityException
이 발생하는 경우 호출자가 승인되지 않았거나 권한이 요청되지 않았을 때 발생합니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
필요
매개변수 | |
---|---|
adSelectionConfig |
AdSelectionConfig : 이 값은 null 일 수 없습니다. |
executor |
Executor : 이 값은 null 일 수 없습니다.
콜백 및 리스너 이벤트가 이 Executor 를 통해 전달되므로 사용되는 스레드를 쉽게 제어할 수 있습니다. 애플리케이션의 기본 스레드를 통해 이벤트를 전달하려면 Context.getMainExecutor() 를 사용하면 됩니다.
그 외의 경우에는 적절한 스레드에 전달되는 Executor 를 제공합니다. |
receiver |
OutcomeReceiver : 이 값은 null 일 수 없습니다. |
updateAdCounterHistogram(업데이트 관련 카운터 히스토그램)
public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)
이전에 selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver)
호출로 선택된 광고의 카운터 히스토그램을 업데이트합니다.
카운터 히스토그램은 광고 선택에 사용되어 조합 광고의 최대 게재빈도 필터링에 관해 알립니다. 여기서 최대 게재빈도가 충족되거나 이를 초과하는 광고는 광고 선택 중에 입찰 프로세스에서 삭제됩니다.
카운터 히스토그램은 동일한 호출자 앱에서 최근의 FLEDGE 광고 선택 호출에서 반환된 지정된 adSelectionId
에 의해 지정된 광고에 대해서만 업데이트될 수 있습니다.
다음과 같은 경우 outcomeReceiver
를 통해 SecurityException
가 반환됩니다.
- 앱이 매니페스트에서 올바른 권한을 선언하지 않은 경우
callerAdTechIdentifier
에 의해 식별된 앱 또는 법인이 API를 사용할 권한이 없는 경우
outcomeReceiver
를 통해 IllegalStateException
가 반환됩니다.
호출이 호출 앱의 API 제한을 초과하면 outcomeReceiver
를 통해 LimitExceededException
이 반환됩니다.
다른 모든 실패 사례에서는 outcomeReceiver
가 빈 Object
를 반환합니다. 사용자 개인 정보 보호를 위해 내부 오류는 예외를 통해 반환되지 않습니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
필요
매개변수 | |
---|---|
updateAdCounterHistogramRequest |
UpdateAdCounterHistogramRequest : 이 값은 null 일 수 없습니다. |
executor |
Executor : 이 값은 null 일 수 없습니다.
콜백 및 리스너 이벤트가 이 Executor 를 통해 전달되므로 사용되는 스레드를 쉽게 제어할 수 있습니다. 애플리케이션의 기본 스레드를 통해 이벤트를 전달하려면 Context.getMainExecutor() 를 사용하면 됩니다.
그 외의 경우에는 적절한 스레드에 전달되는 Executor 를 제공합니다. |
outcomeReceiver |
OutcomeReceiver : 이 값은 null 일 수 없습니다. |