AdSelectionManager

get

public static AdSelectionManager get (Context context)

AdSelectionManager의 인스턴스를 생성하는 팩터리 메서드입니다.

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 필요

getTestAdSelectionManager

public TestAdSelectionManager getTestAdSelectionManager ()

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 필요

보고서 이벤트

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 필요

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을 발생시킵니다.

1. registerAdBeacon가 두 번 이상 호출됩니다. 이 오류가 reportWin/reportResult에서 발견되면 원래 쌍이 등록됩니다.
2. registerAdBeacon에는 정확히 1개의 사전 인수가 없습니다.
3. 1 dict 인수의 콘텐츠는 모든 String: String 쌍이 아닙니다.

출력은 receiver에 의해 전달되어 성공적인 실행을 위해 빈 Object를 반환하거나 Exception에 발생한 예외 유형과 이에 상응하는 오류 메시지가 포함됩니다.

IllegalArgumentException이 발생하는 경우 이 문제는 API가 노출을 보고하기 위해 수신한 잘못된 입력 인수로 인해 발생합니다.

'AdSelection Services 실패' 오류 메시지와 함께 IllegalStateException이 발생하면 광고 선택 서비스의 내부 실패로 인해 발생합니다.

LimitExceededException이 발생하는 경우 호출 패키지가 허용 비율 제한을 초과하여 제한될 때 발생합니다.

SecurityException이 발생하는 경우 호출자가 승인되지 않았거나 권한이 요청되지 않았을 때 발생합니다.

노출은 최선의 시도로 최대 한 번 보고됩니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE 필요

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 필요

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 필요

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가 반환됩니다.

1. 앱이 매니페스트에서 올바른 권한을 선언하지 않은 경우
2. callerAdTechIdentifier에 의해 식별된 앱 또는 법인이 API를 사용할 권한이 없는 경우

호출이 호출 앱의 API 제한을 초과하면 outcomeReceiver를 통해 LimitExceededException이 반환됩니다.

다른 모든 실패 사례에서는 outcomeReceiver가 빈 Object를 반환합니다. 사용자 개인 정보 보호를 위해 내부 오류는 예외를 통해 반환되지 않습니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE 필요