AdSelectionManager

public class AdSelectionManager
extends Object

java.lang.Object
   ↳ android.adservices.adselection.AdSelectionManager

AdSelection Manager는 앱과 광고 SDK에서 광고 선택 프로세스를 실행할 뿐만 아니라 노출수를 보고합니다.

요약

공개 메서드

static AdSelectionManager get(Context context)

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

void getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

기기에서 맞춤 잠재고객 데이터를 수집합니다.

TestAdSelectionManager getTestAdSelectionManager()
void persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

서버 측에서 광고 선택 결과를 유지합니다.

void reportEvent(ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)

선택한 광고에 대해 보고할 새 광고 이벤트가 있음을 서비스에 알립니다. adSelectionId에서 식별한 광고 선택 실행입니다.

void reportImpression(ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)

선택한 광고에 대해 보고할 새로운 노출이 있음을 서비스에 알립니다. adSelectionId에서 식별한 광고 선택 실행입니다.

void selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

이전에 실행한 광고 선택의 결과에서 광고를 선택합니다.

void selectAds(AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

기기에서 광고 선택 프로세스를 실행하여 호출자에 대한 리마케팅 광고를 선택합니다. 애플리케이션입니다.

void updateAdCounterHistogram(UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)

이전에 selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) 호출로 선택한 광고의 카운터 히스토그램을 업데이트합니다.

상속된 메서드

공개 메서드

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이(가) 있어야 합니다.

결과를 처리하는 방법은 AdSelectionManager#persistAdSelectionResult를 참고하세요. 이 API에 의해 생성된 blob을 사용하여 서버 측에서 광고 선택이 실행됩니다.

수신기에서 출력이 전달되며, 이는 성공적인 실행을 위해 GetAdSelectionDataOutcome를 반환하거나 Exception에 다음 유형이 포함됩니다. 발생한 예외와 해당 오류 메시지를 확인할 수 있습니다.

IllegalArgumentException이 발생한 경우 잘못된 입력 인수로 인해 발생한 것입니다. 광고 선택을 실행하기 위해 수신된 API입니다.

'AdSelection of AdSelection'이라는 오류 메시지와 함께 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일 수 없습니다.

지속성 광고 선택 결과

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

서버 측에서 광고 선택 결과를 유지합니다. 자세한 내용은 입찰 및 입찰 서비스 설명 자료

암호화된 blob을 생성하여 다음을 수행하는 방법은 AdSelectionManager#getAdSelectionData를 참조하세요. 서버 측에서 광고 선택을 실행합니다

수신기가 출력을 전달하며 이는 AdSelectionOutcome를 반환합니다. 또는 Exception에 발생한 예외 유형과 확인할 수 있습니다

IllegalArgumentException이 발생한 경우 잘못된 입력 인수로 인해 발생한 것입니다. 광고 선택을 실행하기 위해 수신된 API입니다.

'AdSelection of AdSelection'이라는 오류 메시지와 함께 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()를 사용하여 서비스가 reportingUri registerAdBeacon에 등록된 회사입니다. registerAdBeacon에 관한 자세한 내용은 reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) 문서를 참고하세요. 그런 다음 ReportEventRequest#getData()를 POST 요청의 요청 본문에 연결합니다. 요청을 전송합니다. POST 요청의 본문에는 content-type가 text/plain이며 데이터는 charset=UTF-8로 전송됩니다.

수신기가 출력을 전달하며 이는 다음과 같이 빈 Object를 반환합니다. 또는 Exception에 발생한 예외 유형과 오류 메시지가 표시됩니다.

IllegalArgumentException이 발생한 경우 잘못된 입력 인수로 인해 발생한 것입니다. 광고 이벤트를 보고하기 위해 수신된 API입니다.

'AdSelection of AdSelection'이라는 오류 메시지와 함께 IllegalStateException이 발생하는 경우 광고 선택 서비스의 내부 장애로 인해 발생합니다.

LimitExceededException이 발생한 경우 패키지 호출 시 발생한 것입니다. 허용된 비율 제한을 초과하여 제한됩니다.

SecurityException이 발생한 경우 호출자가 승인되지 않을 때 발생한 것입니다. 또는 권한이 요청되지 않습니다.

이벤트는 최대 1회 최선의 시도로 보고됩니다.
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을 계산하기 위해 서비스는 판매자의 JavaScript ReportImpressionRequest.getAdSelectionConfig()에 있는 AdSelectionConfig#getDecisionLogicUri()의 로직입니다. 그런 다음 서비스는 판매자 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을 계산하기 위해 낙찰자의 구매자의 CustomAudience.getBiddingLogicUri()를 통해 가져오는 JavaScript 로직 그런 다음 구매자 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 } }; }

또한 구매자와 판매자는 특정 제품 및 서비스에 대한 보고서를 수신하도록 등록할 수 있습니다. 지정할 수 있습니다. 이를 위해 플랫폼에서 제공하는 registerAdBeacon 함수를 호출하면 됩니다. 각각 구매자와 판매자의 reportWin 및 reportResult 내부에서 확인할 수 있습니다.

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개의 dict 인수가 없습니다.
  3. 1 dict 인수의 내용은 모두 String: String 쌍이 아닙니다.

출력은 receiver에 의해 전달되며, 이는 빈 Object를 반환합니다. 또는 Exception에 발생한 예외 유형과 확인할 수 있습니다

IllegalArgumentException이 발생한 경우 잘못된 입력 인수로 인해 발생한 것입니다. 노출을 보고할 수 있습니다.

'AdSelection of AdSelection'이라는 오류 메시지와 함께 IllegalStateException이 발생하는 경우 광고 선택 서비스의 내부 장애로 인해 발생합니다.

LimitExceededException이 발생한 경우 패키지 호출 시 발생한 것입니다. 허용된 비율 제한을 초과하여 제한됩니다.

SecurityException이 발생한 경우 호출자가 승인되지 않을 때 발생한 것입니다. 또는 권한이 요청되지 않습니다.

노출수는 최선의 시도로 최대 1회 보고됩니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE 필요

매개변수
request ReportImpressionRequest: 이 값은 null일 수 없습니다.
executor Executor: 이 값은 null일 수 없습니다.
receiver OutcomeReceiver: 이 값은 null일 수 없습니다.

광고 선택

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

이전에 실행한 광고 선택의 결과에서 광고를 선택합니다.

입력 adSelectionFromOutcomesConfig는 광고 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이 발생합니다.

    지원되는 내용은 AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri를 참고하세요. <name> 및 필수 <script-generation-parameters>.

IllegalArgumentException이 발생한 경우 잘못된 입력 인수로 인해 발생한 것입니다. 광고 선택을 실행하기 위해 수신된 API입니다.

'AdSelection of AdSelection'이라는 오류 메시지와 함께 IllegalStateException이 발생하는 경우 광고 선택 서비스의 내부 장애로 인해 발생합니다.

TimeoutException이 발생한 경우 시간 초과가 발생했을 때 발생한 것입니다. 입찰, 점수 또는 전체 선정 과정에서 낙찰된 광고를 찾습니다.

LimitExceededException이 발생한 경우 패키지 호출 시 발생한 것입니다. 허용된 비율 제한을 초과하여 제한됩니다.

SecurityException이 발생한 경우 호출자가 승인되지 않을 때 발생한 것입니다. 또는 권한이 요청되지 않습니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE 필요

매개변수
adSelectionFromOutcomesConfig AdSelectionFromOutcomesConfig: 이 값은 null일 수 없습니다.
executor Executor: 이 값은 null일 수 없습니다. 콜백과 리스너 이벤트는 다음을 통해 전달됩니다. Executor: 어떤 스레드를 실행할지 쉽게 제어할 수 있게 함 있습니다. 앱의 기본 스레드를 통해 이벤트를 애플리케이션의 Context.getMainExecutor() 그 외의 경우에는 적절한 스레드로 전달되는 Executor를 제공합니다.
receiver OutcomeReceiver: 이 값은 null일 수 없습니다.

광고 선택

API 수준 34에 추가됨 
public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

기기에서 광고 선택 프로세스를 실행하여 호출자에 대한 리마케팅 광고를 선택합니다. 애플리케이션입니다.

입력 adSelectionConfig는 광고 SDK에서 제공하고 AdSelectionConfig 객체는 바인더 호출을 통해 전송됩니다. 따라서 전체 크기는 Android IPC 제한을 준수해야 합니다. AdSelectionConfig 전송에 실패하면 TransactionTooLargeException이 발생합니다.

입력 adSelectionConfig에는 뒤에 올 수 있는 Decision Logic Uri가 포함되어 있습니다. 사전 빌드된 광고 선택 스키마를 사용해야 합니다

URI가 HTTPS 스키마를 따르는 경우 호스트는 seller와 일치해야 합니다. 그렇지 않으면 IllegalArgumentException이 발생합니다.

사전 빌드된 URI는 사전 빌드된 일반적인 로직을 scoreAds용 JavaScript입니다. 이 엔드포인트의 사전 빌드된 URI는 다음을 따라야 합니다.

  • ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

지원되지 않는 사전 빌드된 URI가 전달되거나 사전 빌드된 URI 기능이 서비스에서 IllegalArgumentException이 발생합니다.

AdSelectionConfig.Builder#setDecisionLogicUri에서 지원되는 <name> 및 필수 <script-generation-parameters>입니다.

수신기가 출력을 전달하며 이는 AdSelectionOutcome를 반환합니다. 또는 Exception에 발생한 예외 유형과 확인할 수 있습니다

IllegalArgumentException이 발생한 경우 잘못된 입력 인수로 인해 발생한 것입니다. 광고 선택을 실행하기 위해 수신된 API입니다.

'AdSelection of AdSelection'이라는 오류 메시지와 함께 IllegalStateException이 발생하는 경우 광고 선택 서비스의 내부 장애로 인해 발생합니다.

TimeoutException이 발생한 경우 시간 초과가 발생했을 때 발생한 것입니다. 입찰, 점수 또는 전체 선정 과정에서 낙찰된 광고를 찾습니다.

LimitExceededException이 발생한 경우 패키지 호출 시 발생한 것입니다. 허용된 비율 제한을 초과하여 제한됩니다.

SecurityException이 발생한 경우 호출자가 승인되지 않을 때 발생한 것입니다. 또는 권한이 요청되지 않습니다.
AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE 필요

매개변수
adSelectionConfig AdSelectionConfig: 이 값은 null일 수 없습니다.
executor Executor: 이 값은 null일 수 없습니다. 콜백과 리스너 이벤트는 다음을 통해 전달됩니다. Executor: 어떤 스레드를 실행할지 쉽게 제어할 수 있게 함 있습니다. 앱의 기본 스레드를 통해 이벤트를 애플리케이션의 Context.getMainExecutor() 그 외의 경우에는 적절한 스레드로 전달되는 Executor를 제공합니다.
receiver OutcomeReceiver: 이 값은 null일 수 없습니다.

updateAdCounter히스토그램

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를 사용할 수 있습니다.
를 통해 개인정보처리방침을 정의할 수 있습니다. 호출이 다음과 같은 경우 outcomeReceiver를 통해 IllegalStateException이 반환됩니다. 포그라운드 활동이 있는 앱에서 발생하지 않습니다.

호출이 다음과 같은 경우 outcomeReceiver를 통해 LimitExceededException이 반환됩니다. 호출 앱의 API 제한을 초과하는 경우

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

매개변수
updateAdCounterHistogramRequest UpdateAdCounterHistogramRequest: 이 값은 null일 수 없습니다.
executor Executor: 이 값은 null일 수 없습니다. 콜백과 리스너 이벤트는 다음을 통해 전달됩니다. Executor: 어떤 스레드를 실행할지 쉽게 제어할 수 있게 함 있습니다. 앱의 기본 스레드를 통해 이벤트를 애플리케이션의 Context.getMainExecutor() 그 외의 경우에는 적절한 스레드로 전달되는 Executor를 제공합니다.
outcomeReceiver OutcomeReceiver: 이 값은 null일 수 없습니다.