Android 개발자 가이드의 FLEDGE

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

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의 개인 정보 보호 샌드박스 지원이 포함된 에뮬레이터를 설정합니다.

맞춤 잠재고객에 참여

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

  1. CustomAudienceManager 객체를 초기화합니다.
  2. 구매자의 패키지와 관련 이름과 같은 주요 매개변수를 지정하여 CustomAudience 객체를 만듭니다. 그런 다음 JoinCustomAudienceRequest 객체를 CustomAudience 객체로 초기화합니다.
  3. JoinCustomAudienceRequest 객체와 관련 ExecutorOutcomeReceiver 객체를 사용하여 비동기 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, buyername 매개변수와 함께 기존 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("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("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. 맞춤 잠재고객의 owner, buyer, name을 사용하여 LeaveCustomAudienceRequest를 초기화합니다. 이러한 입력 필드에 관한 자세한 내용은 '맞춤 잠재고객에 참여'를 참고하세요.
  3. LeaveCustomAudienceRequest 객체와 관련 ExecutorOutcomeReceiver 객체를 사용하여 비동기 leaveCustomAudience() 메서드를 호출합니다.

Kotlin

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

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder()
        .setOwner(owner)
        .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()
        .setOwner(owner)
        .setBuyer(buyer)
        .setName(name)
        .build();

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

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

광고 선택 실행

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

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

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.runAdSelection(
    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.runAdSelection(
    adSelectionConfig,
    executor,
    outcomeReceiver);

runAdSelection() 메서드에는 다음 필수 매개변수를 지정해야 하는 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을 제공합니다.

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

광고 노출 보고

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

  1. AdSelectionManager 객체를 초기화합니다.
  2. 광고 선택 ID가 있는 ReportImpressionRequest 객체를 빌드합니다.
  3. AdSelectionConfig 객체와 관련 ExecutorOutcomeReceiver 객체를 사용하여 비동기 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로 식별되는 runAdSelection() 호출에 사용된 것과 동일한 구성입니다.

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

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

노출 보고 엔드포인트

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

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

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

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

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

최적의 노출 보고

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

광고 선택을 위한 자바스크립트

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

구매자 제공 자바스크립트는 맞춤 잠재고객에 지정된 입찰 로직 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, buyername은 광고 선택에 참여 중인 맞춤 잠재고객과 동일한 이름을 가진 속성에서 가져온 문자열입니다.
    • activation_timeexpiration_time은 맞춤 잠재고객의 활성화 시간 및 만료 시간으로, Unix 에포크 이후 초 단위로 표현됩니다.
    • ca_user_bidding_signals는 생성 시 CustomAudienceuserBiddingSignals 필드에 지정된 JSON 문자열입니다.
    • trusted_bidding_signals, contextual_signalsuser_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: runAdSelection 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: scoreAds의 문서를 참고하세요.
  • signals_for_buyer: reportResult에서 반환한 JSON 객체
  • contextual_signals, custom_audience_signals: generateBid 관련 문서 참고

출력:

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

테스트

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

기본 요건

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

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

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

HTTPS 엔드포인트

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

  1. 입찰 로직 자바스크립트를 처리하는 구매자 엔드포인트
  2. 결정 로직 자바스크립트를 처리하는 판매자 엔드포인트
  3. 낙찰자 노출 보고 엔드포인트
  4. 판매자 노출 보고 엔드포인트

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

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

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

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

<application
  android:debuggable="true">

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

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

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

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

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

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

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

Kotlin

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

// 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
adSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

자바

AdSelectionManager 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();

// 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
adSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

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

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

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

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

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

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

판매 측 재정의 재설정

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

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

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

Kotlin

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

자바

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

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

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

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

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

Kotlin

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

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setOwner(owner)
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingData(trustedBiddingData)
    .build()

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

자바

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

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setOwner(owner)
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingData(trustedBiddingData)
        .build();

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

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

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

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

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

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

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

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

구매측 재정의 재설정

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

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

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

Kotlin

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

자바

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

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

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

보고 서버 설정

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

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

테스트할 기능

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

제한사항

진행 중인 기능 목록은 출시 노트를 참고하세요.

버그 및 문제 신고

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