Android의 FLEDGE 개발자 가이드

안내가 다를 수 있으므로 Android의 개인 정보 보호 샌드박스 문서를 읽으면서 개발자 프리뷰 또는 베타 버튼을 사용하여 작업 중인 프로그램 버전을 선택하세요.

의견 보내기

Android의 FLEDGE에는 Custom Audience API와 Ad Selection API가 포함되어 있습니다. 광고 기술 플랫폼과 광고주는 앱 간 식별자 공유를 제한하고 사용자의 앱 상호작용 정보를 서드 파티와 공유하는 것을 제한하는 이전 앱 참여를 토대로 맞춤 광고를 처리하는 데 다음 API를 사용할 수 있습니다.

Custom Audience API는 공통의 의도가 있는 사용자 그룹을 나타내는 '맞춤 잠재고객' 추상화를 중심으로 합니다. 광고주는 맞춤 잠재고객이 있는 사용자를 등록하고 관련 광고를 이에 연결할 수 있습니다. 이 정보는 로컬에 저장되며 광고주 입찰, 광고 필터링 및 광고 렌더링을 알리는 데 사용될 수 있습니다.

Ad Selection API는 여러 개발자가 맞춤 잠재고객을 대상으로 로컬에서 입찰을 실행할 수 있는 프레임워크를 제공합니다. 이를 위해 시스템은 맞춤 잠재고객과 연결된 관련 광고를 고려하고, 광고 기술 플랫폼을 통해 기기에 반환되는 광고에 추가 처리를 실행합니다.

광고 기술 플랫폼은 이러한 API를 통합하여 사용자 개인 정보 보호를 보존하는 리마케팅을 구현할 수 있습니다. 앱 설치 광고를 비롯한 추가 사용 사례 지원은 향후 출시 버전에 계획되어 있습니다. Android의 FLEDGE에 관한 자세한 내용은 디자인 제안을 참고하세요.

이 개발자 가이드에는 Android의 FLEDGE를 사용하여 다음을 진행하는 방법이 설명되어 있습니다.

  1. 맞춤 잠재고객 관리
  2. 기기에서 광고 선택 설정 및 실행
  3. 광고 노출 보고

시작하기 전에

시작하기 전에 다음을 완료하세요.

  1. Android의 개인 정보 보호 샌드박스의 개발 환경을 설정합니다.
  2. 지원되는 기기에 시스템 이미지를 설치하거나 Android의 개인 정보 보호 샌드박스 지원이 포함된 에뮬레이터를 설정합니다.

  3. 터미널에서 다음 adb 명령어를 사용하여 FLEDGE API에 대한 액세스를 사용 설정합니다(기본적으로 사용 중지되어 있음).

      adb shell device_config put adservices ppapi_app_allow_list \"*\"

  4. 앱 매니페스트에 ACCESS_ADSERVICES_CUSTOM_AUDIENCE 권한을 포함합니다.

      <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />

  5. 매니페스트의 <application> 요소에서 광고 서비스 구성을 참조합니다.

      <property android:name="android.adservices.AD_SERVICES_CONFIG"
            android:resource="@xml/ad_services_config" />

  6. 매니페스트에 참조된 광고 서비스 XML 리소스를 지정합니다(예: res/xml/ad_services_config.xml). 광고 서비스 권한 및 SDK 액세스 제어에 관해 자세히 알아보세요.

      <ad-services-config>
    <custom-audiences allowAllToAccess="true" />
  </ad-services-config>

  7. 기본적으로 Ad Selection API는 입찰 또는 노출 보고 스크립트에서 할당할 수 있는 최대 메모리 양을 제한합니다. 메모리 제한 기능을 사용하려면 WebView 버전 105.0.5195.58 이상이 필요합니다. 플랫폼은 버전 확인을 시행하고 조건이 충족되지 않으면 selectAds 및 reportImpression API 호출이 실패합니다. 이를 설정하는 옵션에는 두 가지가 있습니다.

    • 옵션 1: 다음 adb 명령어를 실행하여 버전 확인을 사용 중지합니다.

      adb device_config put fledge_js_isolate_enforce_max_heap_size false

    • 옵션 2: Google Play 스토어에서 WebView 베타를 설치합니다. 이는 위에 언급된 버전 이상이어야 합니다.

맞춤 잠재고객에 참여

맞춤 잠재고객은 광고주 앱에 의해 결정되는, 공통의 의도나 관심분야가 있는 사용자 그룹을 나타냅니다. 앱 또는 SDK는 맞춤 잠재고객을 사용하여 장바구니에 상품이 남아 있는 사용자와 같은 특정 잠재고객을 나타낼 수 있습니다. 맞춤 잠재고객을 비동기식으로 만들거나 맞춤 잠재고객에 참여하려면 다음을 수행하세요.

  1. CustomAudienceManager 객체를 초기화합니다.
  2. 구매자의 패키지와 관련 이름과 같은 주요 매개변수를 지정하여 CustomAudience 객체를 만듭니다. 그런 다음 JoinCustomAudienceRequest 객체를 CustomAudience 객체로 초기화합니다.
  3. JoinCustomAudienceRequest 객체와 관련 Executor 및 OutcomeReceiver 객체를 사용하여 비동기 joinCustomAudience()를 호출합니다.

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

자바

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

다음 매개변수의 조합은 CustomAudience 기기의 각 객체를 고유하게 식별합니다.

  • owner: 소유자 앱의 패키지 이름입니다. 암시적으로 호출자 앱의 패키지 이름으로 설정됩니다.
  • buyer: 이 맞춤 잠재고객의 광고를 관리하는 구매자 광고 네트워크의 식별자입니다.
  • name: 맞춤 잠재고객의 임의 이름 또는 식별자입니다.

CustomAudience의 다른 인스턴스를 사용하여 joinCustomAudience()를 반복적으로 호출하면 일치하는 owner, buyer 및 name 매개변수와 함께 기존 CustomAudience가 업데이트됩니다. 개인 정보 보호를 유지하기 위해 API의 결과는 '생성'과 '업데이트'를 구분하지 않습니다.

또한 CustomAudience는 다음 필수 매개변수를 사용하여 만들어야 합니다.

  • 일일 업데이트 URL: 맞춤 잠재고객의 사용자 입찰 신호, 신뢰할 수 있는 입찰 데이터, 렌더링 URL 및 광고 메타데이터를 업데이트하기 위해 백그라운드에서 매일 쿼리되는 HTTPS URL입니다.
  • 입찰 로직 URL: 광고 선택 중에 구매자의 자바스크립트 입찰 로직을 가져오기 위해 쿼리되는 HTTPS URL입니다. 이 자바스크립트에서 필수 함수 서명을 참고하세요.

CustomAudience 객체의 선택적 매개변수는 다음과 같습니다.

  • 활성화 시간: 맞춤 잠재고객은 활성화 시간 이후에만 광고 선택과 일일 업데이트에 참여할 수 있습니다. 이는 예를 들어 앱 사용을 중단한 사용자의 참여를 유도하는 데 유용할 수 있습니다.
  • 만료 시간: 맞춤 잠재고객이 기기에서 삭제되기까지 남은 미래 시간입니다.
  • 사용자 입찰 신호: 광고 선택 프로세스에서 구매자의 입찰 로직 자바스크립트가 입찰 생성에 사용하는 사용자 신호(예: 사용자의 선호 언어)가 포함된 JSON 문자열입니다. 이 형식은 광고 기술 플랫폼이 여러 플랫폼 간의 코드를 재사용하는 데 도움이 되고 자바스크립트 함수 사용을 용이하게 해 줍니다.
  • 신뢰할 수 있는 입찰 데이터: 광고 선택 프로세스 중에 신뢰할 수 있는 키/값 서버에서 입찰 신호를 가져오는 데 사용되는 HTTPS URL 및 문자열 목록입니다.
  • 광고: 광고 선택에 참여할 광고에 해당하는 AdData 객체의 목록입니다. 각 AdData 객체는 다음으로 구성됩니다.
    • 렌더링 URL: 최종 광고를 렌더링하기 위해 쿼리되는 HTTPS URL입니다.
    • 메타데이터: 광고 선택 프로세스 중에 구매자 입찰 로직에 사용할 정보가 포함된 JSON 객체(문자열로 직렬화됨)입니다.

다음은 CustomAudience 객체 인스턴스화의 예입니다.

Kotlin

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

자바

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

joinCustomAudience() 결과 처리

비동기 joinCustomAudience() 메서드는 OutcomeReceiver 객체를 사용하여 API 호출의 결과를 알립니다.

  • onResult() 콜백은 맞춤 잠재고객을 성공적으로 생성했거나 업데이트했음을 나타냅니다.
  • onError() 콜백은 두 가지 가능한 조건을 나타냅니다.

다음은 joinCustomAudience()의 결과를 처리하는 예입니다.

Kotlin

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

자바

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

맞춤 잠재고객 탈퇴

사용자가 지정된 맞춤 잠재고객의 비즈니스 기준을 더 이상 충족하지 않으면 앱 또는 SDK가 leaveCustomAudience()를 호출하여 기기에서 맞춤 잠재고객을 삭제할 수 있습니다. 고유한 매개변수를 기반으로 CustomAudience를 삭제하려면 다음을 실행합니다.

  1. CustomAudienceManager 객체를 초기화합니다.
  2. 맞춤 잠재고객의 buyer 및 name을 사용하여 LeaveCustomAudienceRequest를 초기화합니다. 이러한 입력 필드에 관한 자세한 내용은 '맞춤 잠재고객에 참여'를 참고하세요.
  3. LeaveCustomAudienceRequest 객체와 관련 Executor 및 OutcomeReceiver 객체를 사용하여 비동기 leaveCustomAudience() 메서드를 호출합니다.

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

자바

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

joinCustomAudience() 호출과 마찬가지로 OutcomeReceiver는 API 호출 종료를 알립니다. 개인 정보 보호를 위해 오류 결과는 내부 오류와 잘못된 인수를 구분하지 않습니다. onResult() 콜백은 일치하는 맞춤 잠재고객이 제대로 삭제되었는지에 상관없이 API 호출이 완료되면 호출됩니다.

광고 선택 실행

FLEDGE를 사용하여 광고를 선택하려면 selectAds() 메서드를 호출합니다.

  1. AdSelectionManager 객체를 초기화합니다.
  2. AdSelectionConfig 객체를 빌드합니다.
  3. AdSelectionConfig 객체와 관련 Executor 및 OutcomeReceiver 객체를 사용하여 비동기 selectAds() 메서드를 호출합니다.

Kotlin

val adSelectionManager: AdSelectionManager =
    context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
        AdSelectionConfig.Builder()
                .setSeller(seller)
                .setDecisionLogicUrl(decisionLogicUrl)
                .setCustomAudienceBuyers(customAudienceBuyers)
                .setAdSelectionSignals(adSelectionSignals)
                .setSellerSignals(sellerSignals)
                .setPerBuyerSignals(perBuyerSignals)
                .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver)

자바

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
        new AdSelectionConfig.Builder()
                .setSeller(seller)
                .setDecisionLogicUrl(decisionLogicUrl)
                .setCustomAudienceBuyers(customAudienceBuyers)
                .setAdSelectionSignals(adSelectionSignals)
                .setSellerSignals(sellerSignals)
                .setPerBuyerSignals(perBuyerSignals)
                .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver);

selectAds() 메서드에는 다음 필수 매개변수를 지정해야 하는 AdSelectionConfig 입력이 필요합니다.

  • 판매자: 광고 선택을 시작하는 판매자 광고 네트워크의 식별자입니다.
  • 결정 로직 URL: 판매자 광고 네트워크의 자바스크립트 로직을 가져오기 위해 쿼리되는 HTTPS URL입니다. 이 자바스크립트에서 필수 함수 서명을 참고하세요.
  • 맞춤 잠재고객 구매자: 판매자가 광고 선택 프로세스에 참여할 수 있도록 허용한 구매자 광고 네트워크의 전체 식별자 목록입니다. 이러한 구매자 식별자는 참여하는 맞춤 잠재고객의 CustomAudience.getBuyer()에 해당합니다.

원하는 경우 다음 매개변수를 지정하여 광고 선택을 더욱 맞춤설정할 수 있습니다.

  • 광고 선택 신호: CustomAudience.getBiddingLogicUrl()에서 가져온 구매자 입찰 로직 자바스크립트에 사용할 신호를 포함하는 JSON 객체(문자열로 직렬화됨)입니다.
  • 판매자 신호: 판매자가 AdSelectionConfig.getDecisionLogicUrl()에서 가져온 자바스크립트 결정 로직에 사용되는 신호가 포함된 JSON 객체(문자열로 직렬화됨)입니다.
  • 구매자 신호별: CustomAudience.getBiddingLogicUrl()에서 가져온 특정 구매자의 입찰 로직 자바스크립트에 사용되는 신호가 포함된 JSON 객체(문자열로 직렬화됨)의 맵입니다. 이러한 객체는 참여하는 맞춤 잠재고객의 구매자 필드를 통해 식별됩니다.

광고가 선택되면 결과, 입찰, 신호는 이후 보고 목적으로 내부적으로 유지됩니다. OutcomeReceiver.onResult() 콜백에서 다음을 포함하는 AdSelectionOutcome을 다시 가져옵니다.

  • AdData.getRenderUrl()에서 가져온 낙찰 광고의 렌더링 URL
  • 기기 사용자의 고유한 광고 선택 ID. 이 ID는 광고 노출을 보고하는 데 사용됩니다.

잘못된 인수, 시간 초과, 과도한 리소스 사용 같은 이유로 인해 광고 선택을 제대로 완료할 수 없는 경우 OutcomeReceiver.onError() 콜백이 다음 동작과 함께 AdServicesException을 제공합니다.

  • 잘못된 인수로 광고 선택이 시작되면 AdServicesException은 IllegalArgumentException을 원인으로 나타냅니다.
  • 그 외 모든 오류에서는 IllegalStateException이 원인으로 표시된 AdServicesException을 수신하게 됩니다.

광고 노출 보고

광고 선택 워크플로에서 낙찰된 광고를 선택한 후에는 AdSelectionManager.reportImpression() 메서드를 사용하여, 참여 중인 구매 측 플랫폼과 판매 측 플랫폼에 노출을 다시 보고할 수 있습니다. 광고 노출을 보고하는 방법은 다음과 같습니다.

  1. AdSelectionManager 객체를 초기화합니다.
  2. 광고 선택 ID가 있는 ReportImpressionRequest 객체를 빌드합니다.
  3. AdSelectionConfig 객체와 관련 Executor 및 OutcomeReceiver 객체를 사용하여 비동기 reportImpression() 메서드를 호출합니다.

자바

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest adSelectionConfig =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig);
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

Kotlin

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig);
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

다음 필수 매개변수를 사용하여 ReportImpressionRequest를 초기화합니다.

  • 광고 선택 ID: 성공한 광고 선택을 식별하는 기기 사용자 전용의 고유 ID입니다.
  • 광고 선택 구성: 제공된 광고 선택 ID로 식별되는 selectAds() 호출에 사용된 것과 동일한 구성입니다.

비동기 reportImpression() 메서드는 OutcomeReceiver 객체를 사용하여 API 호출의 결과를 알립니다.

  • onResult() 콜백은 광고 선택이 완료되었는지를 나타냅니다.
  • onError() 콜백은 다음과 같은 가능한 조건을 나타냅니다.
    • 잘못된 입력 인수로 호출이 초기화되면 AdServicesException은 IllegalArgumentException을 원인으로 나타냅니다.
    • 그 외 모든 오류에서는 IllegalStateException이 원인으로 표시된 AdServicesException을 수신하게 됩니다.

노출 보고 엔드포인트

Report impression API가 판매 측 플랫폼과 낙찰된 구매 측 플랫폼에서 제공한 엔드포인트에 HTTPS GET 요청을 발행합니다.

구매 측 플랫폼 엔드포인트:

  • API는 맞춤 잠재고객에 지정된 입찰 로직 URL을 사용하여 구매자의 입찰 로직 자바스크립트를 가져옵니다.
  • 구매자의 노출 보고 URL을 반환해야 하는 reportResult() 자바스크립트 함수를 호출합니다.

판매측 플랫폼 엔드포인트:

  • AdSelectionConfig 객체에 지정된 결정 로직 URL을 사용하여 판매자의 결정 로직 자바스크립트를 가져옵니다.
  • 구매자의 노출 보고 URL을 반환해야 하는 reportWin() 자바스크립트 함수를 호출합니다.

최적의 노출 보고

reportImpression()은 최적으로 보고를 완료하도록 설계되었습니다.

일일 백그라운드 업데이트

맞춤 잠재고객을 만들 때 앱 또는 SDK에서는 맞춤 잠재고객 메타데이터를 초기화할 수 있습니다. 또한 플랫폼에서는 일일 백그라운드 업데이트 프로세스로 다음과 같은 맞춤 잠재고객 메타데이터를 업데이트할 수 있습니다.

  • 사용자 입찰 신호
  • 신뢰할 수 있는 입찰 데이터
  • AdData 목록

이 프로세스는 맞춤 잠재고객에 정의된 일일 업데이트 URL을 대상으로 쿼리하며 이 URL은 JSON 응답을 반환할 수 있습니다.

  • JSON 응답에는 업데이트해야 하는, 지원되는 메타데이터 필드가 포함될 수 있습니다.
  • 각 JSON 필드는 독립적으로 검증됩니다. 클라이언트는 잘못된 형식의 필드를 무시하므로 응답에서 해당 필드가 업데이트되지 않습니다.
  • 빈 HTTP 응답이나 빈 JSON 객체 '{}'로 인해 메타데이터가 업데이트되지 않습니다.
  • 응답 메시지 크기는 10KB로 제한해야 합니다.
  • 모든 URI는 HTTPS를 사용해야 합니다.
  • trusted_bidding_uri는 구매자와 동일한 ETLD+1을 공유해야 합니다.

예: 백그라운드 일일 업데이트 JSON 응답

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

일반적으로 이 백그라운드 가져오기는 24시간마다 한 번씩 발생합니다. 테스트하는 동안 다음 명령어를 실행하여 이 작업을 수동으로 트리거할 수 있습니다.

adb shell cmd jobscheduler run -f com.google.android.adservices.api 9

광고 선택을 위한 JavaScript

광고 선택 워크플로는 구매자 제공 자바스크립트와 판매자 제공 자바스크립트의 실행을 조정합니다.

구매자 제공 자바스크립트는 맞춤 잠재고객에 지정된 입찰 로직 URL에서 가져옵니다. 반환된 자바스크립트에는 다음 함수가 포함되어야 합니다.

판매자 제공 자바스크립트는 광고 선택 API의 AdSelectionConfig 매개변수에 지정된 결정 로직 URL에서 가져오게 됩니다. 반환된 자바스크립트에는 다음 함수가 포함되어야 합니다.

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

입력 매개변수:

  • ad: ad = { 'render_url': url, 'metadata': json_metadata } 형식의 변수가 있는 JSON 객체
  • auction_signals, per_buyer_signals: JSON 객체로, 입찰 구성 객체에 지정됩니다.

  • custom_audience_signals: 플랫폼에서 생성된 JSON 객체입니다. 이 JSON 객체의 형식은 다음과 같습니다.

    var custom_audience_signals = {
  "owner":"ca_owner",
  "buyer":"ca_buyer",
  "name":"ca_name",
  "activation_time":"ca_activation_time_epoch_ms",
  "expiration_time":"ca_expiration_time_epoch_ms",
  "user_bidding_signals":"ca_user_bidding_signals"
}

    여기에서:

    • owner, buyer 및 name은 광고 선택에 참여 중인 맞춤 잠재고객과 동일한 이름을 가진 속성에서 가져온 문자열입니다.
    • activation_time 및 expiration_time은 맞춤 잠재고객의 활성화 시간 및 만료 시간으로, Unix 에포크 이후 초 단위로 표현됩니다.
    • ca_user_bidding_signals는 생성 시 CustomAudience의 userBiddingSignals 필드에 지정된 JSON 문자열입니다.
    • trusted_bidding_signals, contextual_signals 및 user_signals는 JSON 객체입니다. 현재 이러한 객체는 빈 객체로 전달되며 향후 출시 버전에서 채워질 예정입니다. 객체의 형식은 플랫폼에 의해 적용되지 않으며 광고 기술을 통해 관리됩니다.

결과:

  • ad: 입찰에 참조되는 광고입니다. 스크립트는 다양한 메타데이터와 함께 수신한 광고의 사본을 반환할 수 있습니다. 광고의 render_url 속성은 변경되지 않아야 합니다.
  • bid: 이 광고의 입찰가를 나타내는 부동 소수점 값
  • status: 정수로, 다음에 해당할 수 있습니다.
    • 0: 실행이 성공한 경우
    • 1: (또는 0이 아닌 값) 입력 신호가 잘못된 모든 경우. 입찰 생성에 의해 0이 아닌 값이 반환되는 경우 모든 CA 광고의 입찰 프로세스가 무효화됩니다.

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

입력 매개변수:

  • ad: generateBid 문서를 참고하세요.
  • bid: 광고의 입찰가

  • ad_selection_config: selectAds API의 AdSelectionConfig 매개변수를 나타내는 JSON 객체. 형식은 다음과 같습니다.

    var ad_selection_config = {
  'seller': 'seller',
  'decision_logic_url': 'url_of_decision_logic',
  'custom_audience_buyers': ['buyer1', 'buyer2'],
  'auction_signals': auction_signals,
  'per_buyer_signals': per_buyer_signals,
  'contextual_ads': [ad1, ad2]
}

  • seller_signals: sellerSignals AdSelectionConfig API 매개변수에서 읽어온 JSON 객체

  • trusted_scoring_signal: AdSelectionConfig API 매개변수의 adSelectionSignals 필드에서 읽어옴

  • contextual_signals, user_signals: JSON 개체 현재 이러한 객체는 빈 객체로 전달되며 향후 출시 버전에서 채워질 예정입니다. 객체의 형식은 플랫폼에 의해 적용되지 않으며 광고 기술을 통해 관리됩니다.

  • per_buyer_signals: 현재 맞춤 잠재고객 구매자를 키로 사용하여 AdSelectionConfig API 매개변수의 perBuyerSignal 맵에서 읽어온 JSON 객체. 지정된 구매자에 관한 항목이 맵에 없으면 비어 있습니다.

출력:

  • score: 이 광고의 평가 결과를 나타내는 부동 소수점 값
  • status: 정수로, 다음에 해당할 수 있습니다.
    • 0: 실행이 성공한 경우
    • 1: customAudienceSignals가 유효하지 않은 경우
    • 2: AdSelectionConfig가 유효하지 않은 경우
    • 3: 다른 신호가 유효하지 않은 경우
    • 0이 아닌 값으로 인해 프로세스 실패가 발생하며, 발생한 예외 유형이 값에 따라 결정됩니다.

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 }
   };
}

입력 매개변수:

  • ad_selection_config: scoreAds의 문서를 참고하세요.
  • render_url: 낙찰된 광고의 렌더링 URL
  • bid: 낙찰된 광고에 제공된 입찰
  • contextual_signals: generateBid의 문서를 참고하세요.

출력:

  • 성공한 경우에는 status: 0이고, 실패한 경우에는 0이 아닌 값입니다.
  • results: 다음을 포함하는 JSON 객체:
    • signals_for_buyer: reportWin 함수에 전달되는 JSON 객체입니다.
    • reporting_url: 플랫폼에서 구매자에게 노출을 알리는 데 사용하는 URL입니다.

reportWin()

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

입력 매개변수:

  • ad_selection_signals, per_buyer_signals: scoreAd 관련 문서 참고
  • signals_for_buyer: reportResult에서 반환한 JSON 객체
  • contextual_signals, custom_audience_signals: generateBid 관련 문서 참고

출력:

  • 성공한 경우에는 status: 0이고, 실패한 경우에는 0이 아닌 값입니다.
  • results: 다음을 포함하는 JSON 객체:
    • reporting_url: 플랫폼에서 판매자에게 노출을 알리는 데 사용하는 URL

테스트

FLEDGE를 시작하는 데 도움을 드리고자 Kotlin과 Java로 샘플 앱을 만들었으며 이 앱은 GitHub에서 확인할 수 있습니다.

기본 요건

FLEDGE를 사용하려면 광고 선택 및 노출 보고 중에 자바스크립트가 필요합니다. 테스트 환경에서 이 자바스크립트를 제공하는 방법에는 두 가지가 있습니다.

  • 자바스크립트를 반환하는 필수 HTTPS 엔드포인트로 서버를 실행합니다.
  • 로컬 소스에서 필요한 코드를 제공하여 원격 가져오기를 재정의합니다.

두 방법 모두 HTTPS 엔드포인트를 설정하여 노출 보고를 처리해야 합니다.

HTTPS 엔드포인트

광고 선택 및 노출 보고를 테스트하려면 테스트 기기 또는 에뮬레이터가 액세스할 수 있는 다음 7개의 HTTPS 엔드포인트를 설정해야 합니다.

  1. 입찰 로직 자바스크립트를 처리하는 구매자 엔드포인트
  2. 입찰 신호를 처리하는 엔드포인트
  3. 결정 로직 자바스크립트를 처리하는 판매자 엔드포인트
  4. 점수 신호를 처리하는 엔드포인트
  5. 낙찰자 노출 보고 엔드포인트
  6. 판매자 노출 보고 엔드포인트
  7. 맞춤 잠재고객 일일 업데이트를 처리하는 엔드포인트

편의를 위해 GitHub 저장소에서는 테스트 목적으로 기본 JavaScript 코드를 제공합니다. 지원되는 모의 플랫폼 또는 마이크로서비스 플랫폼에 배포할 수 있는 OpenAPI 서비스 정의도 포함하고 있습니다. 자세한 내용은 프로젝트 리드미를 참고하세요.

자바스크립트의 원격 가져오기 재정의

이 기능은 엔드 투 엔드 테스트에 사용하기 위한 것입니다. 원격 가져오기를 재정의하려면 개발자 옵션이 사용 설정된 상태에서 앱을 디버그 모드로 실행해야 합니다.

애플리케이션의 디버그 모드를 사용 설정하려면 AndroidManifest.xml의 애플리케이션 속성에 다음 줄을 추가하세요.

<application
  android:debuggable="true">

이러한 재정의를 사용하는 방법을 보여주는 예는 GitHub의 FLEDGE 샘플 앱을 참고하세요.

입찰, 점수 결정, 보고와 같은 광고 선택 루틴을 처리하려면 자체 맞춤 자바스크립트를 추가해야 합니다. 필요한 모든 요청을 처리하는 기본적인 자바스크립트 코드 예는 GitHub 저장소에서 확인할 수 있습니다. FLEDGE 샘플 애플리케이션은 해당 파일에서 코드를 읽고 재정의로 사용할 수 있도록 준비하는 방법을 보여줍니다.

판매 측 및 구매 측 JavaScript 가져오기를 독립적으로 재정의할 수 있지만 개발자가 재정의를 제공하지 않는 JavaScript를 제공하려면 HTTPS 엔드포인트가 필요합니다. 이러한 사례를 처리하는 서버를 설정하는 방법은 리드미를 참고하세요.

개발자는 자신의 패키지에서 소유한 맞춤 잠재고객의 자바스크립트 가져오기만 재정의할 수 있습니다.

판매 측 자바스크립트 재정의

판매 측 자바스크립트 재정의를 설정하려면 다음을 실행하세요(아래 코드 예 참고).

  1. AdSelectionManager 객체를 초기화합니다.
  2. AdSelectionManager 객체에서 TestAdSelectionManager 참조를 가져옵니다.
  3. AdSelectionConfig 객체를 빌드합니다.
  4. AdSelectionConfig 객체와 재정의로 사용할 자바스크립트를 나타내는 String으로 AddAdSelectionOverrideRequest를 빌드합니다.
  5. AddAdSelectionOverrideRequest 객체와 관련 Executor 및 OutcomeReceiver 객체를 사용하여 비동기 overrideAdSelectionConfigRemoteInfo() 메서드를 호출합니다.

Kotlin

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

자바

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

AdSelectionConfig의 각 필드가 나타내는 항목에 관한 자세한 내용은 광고 선택 실행 섹션을 참고하세요. 주요 차이점은 decisionLogicUrl이 무시되므로 이를 자리표시자 값으로 설정할 수 있다는 것입니다.

광고 선택 중에 사용되는 JavaScript를 재정의하려면 decisionLogicJs에 적절한 판매자 측 함수 서명이 포함되어야 합니다. 자바스크립트 파일을 문자열로 읽는 방법에 관한 예는 GitHub의 FLEDGE 샘플 앱을 참고하세요.

비동기 overrideAdSelectionConfigRemoteInfo() 메서드는 OutcomeReceiver 객체를 사용하여 API 호출의 결과를 알립니다.

onResult() 콜백은 재정의가 적용되었음을 나타냅니다. 향후 selectAds() 호출에서는 개발자가 재정의로 전달한 결정 및 보고 로직을 사용합니다.

onError() 콜백은 두 가지 가능한 조건을 나타냅니다.

  • 잘못된 인수로 재정의를 시도하면 AdServiceException은 IllegalArgumentException을 원인으로 나타냅니다.
  • 개발자 옵션이 사용 설정된 상태에서 디버그 모드로 실행되지 않는 앱으로 재정의를 시도하면 AdServiceException에서 IllegalStateException을 원인으로 표시합니다.

판매 측 재정의 재설정

이 섹션에서는 개발자가 판매 측 자바스크립트를 재정의했으며 이전 섹션에서 사용된 TestAdSelectionManager 및 AdSelectionConfig 참조가 있다고 가정합니다.

모든 AdSelectionConfigs의 재정의를 재설정하려면 다음 안내를 따르세요.

  1. 관련 OutcomeReceiver 객체를 사용하여 비동기 resetAllAdSelectionConfigRemoteOverrides() 메서드를 호출합니다.

Kotlin

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

자바

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

판매 측 재정의를 재설정한 후 selectAds() 호출에서는 AdSelectionConfig에 저장된 decisionLogicUrl을 사용하여 필수 자바스크립트를 가져오려고 합니다.

resetAllAdSelectionConfigRemoteOverrides() 호출이 실패하면 OutComeReceiver.onError() 콜백에서 AdServiceException을 제공합니다. 개발자 옵션이 사용 설정된 상태에서 디버그 모드로 실행되지 않는 앱으로 재정의 삭제를 시도하면 AdServiceException에서 IllegalStateException을 원인으로 표시합니다.

구매 측 자바스크립트 재정의

  1. 단계에 따라 맞춤 잠재고객에 참여합니다.
  2. 재정의할 맞춤 잠재고객의 구매자, 이름과 재정의로 사용하려는 입찰 로직과 데이터를 사용하여 AddCustomAudienceOverrideRequest를 빌드합니다.
  3. AddCustomAudienceOverrideRequest 객체와 관련 Executor 및 OutcomeReceiver 객체를 사용하여 비동기 overrideCustomAudienceRemoteInfo() 메서드를 호출합니다.

Kotlin

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

자바

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

, 구매자, 이름의 값은 맞춤 잠재고객을 만드는 데 사용된 값과 동일합니다. 이 필드에 관해 자세히 알아보기

또한 추가 매개변수 두 개를 지정할 수 있습니다.

  • biddingLogicJs: 광고 선택 중에 사용되는 구매자의 로직을 보유하는 자바스크립트입니다. 이 자바스크립트에서 필수 함수 서명을 참고하세요.
  • trustedBiddingSignals: 광고 선택 중에 사용할 입찰 신호입니다. 테스트 목적으로 이는 빈 문자열일 수 있습니다.

비동기 overrideCustomAudienceRemoteInfo() 메서드는 OutcomeReceiver 객체를 사용하여 API 호출의 결과를 알립니다.

onResult() 콜백은 재정의가 적용되었음을 나타냅니다. 후속 selectAds() 호출에서는 개발자가 재정의로 전달한 입찰 및 보고 로직을 사용합니다.

onError() 콜백은 두 가지 가능한 조건을 나타냅니다.

  • 잘못된 인수로 재정의를 시도하면 AdServiceException은 IllegalArgumentException을 원인으로 나타냅니다.
  • 개발자 옵션이 사용 설정된 상태에서 디버그 모드로 실행되지 않는 앱으로 재정의를 시도하면 AdServiceException에서 IllegalStateException을 원인으로 표시합니다.

구매 측 재정의 재설정

이 섹션에서는 개발자가 구매 측 자바스크립트를 재정의했으며 이전 섹션에서 사용된 TestCustomAudienceManager 참조가 있다고 가정합니다.

모든 맞춤 잠재고객의 재정의를 재설정하려면 다음 안내를 따르세요.

  1. 관련 Executor 및 OutcomeReceiver 객체를 사용하여 비동기 resetAllCustomAudienceOverrides() 메서드를 호출합니다.

Kotlin

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

자바

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

구매 측 재정의를 재설정한 후 후속 selectAds() 호출에서는 CustomAudience에 저장된 biddingLogicUrl 및 trustedBiddingData를 사용하여 필수 자바스크립트를 가져오려고 합니다.

resetCustomAudienceRemoteInfoOverride() 호출이 실패하면 OutComeReceiver.onError() 콜백에서 AdServiceException을 제공합니다. 개발자 옵션이 사용 설정된 상태에서 디버그 모드로 실행되지 않는 앱으로 재정의 삭제를 시도하면 AdServiceException에서 IllegalStateException을 원인으로 표시합니다.

보고 서버 설정

원격 가져오기 재정의를 사용하는 경우에도 기기 또는 에뮬레이터에서 도달할 수 있는 서버를 설정하여 보고 이벤트에 응답해야 합니다. 200을 반환하는 간단한 엔드포인트면 테스트하기에 충분합니다. GitHub 저장소에는 지원되는 모의 플랫폼 또는 마이크로서비스 플랫폼에 배포할 수 있는 OpenAPI 서비스 정의가 포함되어 있습니다. 자세한 내용은 프로젝트 리드미를 참고하세요.

OpenAPI 정의를 찾는 경우 reporting-server.json을 찾으세요. 이 파일에는 HTTP 응답 코드를 나타내는 200을 반환하는 간단한 엔드포인트가 포함되어 있습니다. 이 엔드포인트는 selectAds() 중에 사용되며 노출 보고가 성공적으로 완료되었음을 FLEDGE에 알립니다.

테스트할 기능

  • 이전 사용자 작업을 기반으로 맞춤 잠재고객을 설정하고 이에 가입 또는 탈퇴하는 과정 실행
  • 원격으로 호스팅되는 자바스크립트를 통해 기기 내 광고 선택을 시작하는 과정 실행
  • 앱과 맞춤 잠재고객 설정의 연결이 광고 선택 결과에 미칠 수 있는 영향 관찰
  • 광고 선택 후 노출 보고 실행

제한사항

다음 표에는 FLEDGE 처리 제한사항이 나와 있습니다. 표시된 제한사항은 피드백에 따라 변경될 수 있습니다. 진행 중인 기능은 출시 노트를 참고하세요.

구성요소 제한 설명 제한 값
맞춤 잠재고객(CA) CA당 최대 광고 수 100
애플리케이션당 최대 CA 수 1000
CA를 만들 수 있는 최대 앱 수 1000
생성 시간부터 CA가 활성화될 때까지 걸리는 최대 지연 시간 60일
활성화 시간부터 최대 CA 만료 시간 60일
기기의 최대 CA 수 4000
CA 이름의 최대 크기 200바이트
일일 가져오기 URI의 최대 크기 400바이트
입찰 로직 URI의 최대 크기 400바이트
신뢰할 수 있는 입찰 데이터의 최대 크기 10KB
사용자 입찰 신호의 최대 크기 10KB
구매자당 최대 leaveCustomAudience 호출률 초당 1회
구매자당 최대 joinCustomAudience 호출률 초당 1회
CA 백그라운드 가져오기 연결 시간 제한 5초
HTTP 읽기 시간 제한 30초
최대 총 다운로드 크기 10KB
최대 가져오기 반복 시간 5분
작업당 업데이트되는 최대 CA 수 1000
광고 선택 최대 구매자 수 미정
구매자당 최대 CA 수 미정
입찰 내 최대 광고 수 미정
초기 연결 시간 제한 5초
연결 읽기 시간 제한 5초
전체 AdSelection의 최대 실행 시간 10초
AdSelection에서 CA당 최대 입찰 실행 시간 5초
AdSelection에서 최대 점수 실행 시간 5초
AdSelection에서 구매자당 최대 실행 시간 미정
광고 선택/판매자/구매자당 신호의 최대 크기 미정
판매자/구매자 스크립트의 최대 크기 미정
selectAds의 최대 호출률 1QPS
노출 보고 지속성에서 광고 선택을 삭제하기 전 최소 시간 24시간
최대 저장소 광고 선택 수 미정
보고 출력 URL의 최대 크기 미정
노출 보고 최대 시간 미정
알림 호출의 최대 재시도 횟수 미정
연결 시간 제한 5초
reportImpression의 최대 전체 실행 시간 2초
reportImpressions의 최대 호출률 1QPS
광고 광고 목록의 최대 크기 단일 CA의 모든 AdData에서 공유하는 경우 10KB, 컨텍스트의 경우 미정
URL 입력으로 사용된 URL 문자열의 최대 길이 미정
자바스크립트 최대 실행 시간 노출 보고의 입찰 및 점수 관련 1초
사용한 최대 메모리 10MB

버그 및 문제 신고

여러분의 의견은 Android의 개인 정보 보호 샌드박스에서 매우 중요한 부분입니다. 발견한 문제나 Android의 개인 정보 보호 샌드박스 개선을 위한 아이디어가 있다면 Google에 알려 주세요.