잠재고객 데이터 정의

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

맞춤 잠재고객은 광고주 앱에 의해 결정되는, 공통의 의도나 관심분야가 있는 사용자 그룹을 나타냅니다. 앱 또는 SDK는 맞춤 잠재고객을 사용하여 장바구니에 상품이 남아 있는 사용자와 같은 특정 잠재고객을 나타낼 수 있습니다.

Android Protected Audience API는 사용자의 기기에서 맞춤 잠재고객에 참여하거나 참여를 종료하는 데 사용할 수 있습니다. 맞춤 잠재고객을 만들고 참여할 때 맞춤 잠재고객 속성의 일부 또는 전체를 가져올 서버에 위임하거나 API를 직접 호출할 때 이 정보를 지정할 수 있습니다.

맞춤 잠재고객

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

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

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

• 일일 업데이트 URL: 맞춤 잠재고객의 사용자 입찰 신호, 신뢰할 수 있는 입찰 데이터, 렌더링 URL 및 광고 메타데이터를 업데이트하기 위해 백그라운드에서 매일 쿼리되는 HTTPS URL입니다.
• 입찰 로직 URL: 광고 선택 중에 구매자의 JavaScript 입찰 로직을 가져오기 위해 쿼리되는 HTTPS URL입니다. 이 JavaScript에서 필수 함수 서명을 참고하세요.
• 광고 렌더링 ID: 구매자 광고 기술에서 설정한 임의의 ID입니다. 이는 B&A용 페이로드 생성을 위한 최적화입니다.

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

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

맞춤 잠재고객 가져오기 및 참여

fetchAndJoinCustomAudience API를 사용하면 구매자가 파트너 MMP 또는 SSP의 기기 내 존재를 활용하여 맞춤 잠재고객 참여를 위임할 수 있습니다.

이렇게 하려면 기기 내 호출자 (MMP 또는 SSP SDK)가 다음과 같은 fetchAndJoinCustomAudienceRequest를 만듭니다.

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

모든 선택적 매개변수에 관한 중요한 사항은 가져오기 요청 내에 설정되어 있는 경우 구매자가 반환한 값으로 데이터를 재정의할 수 없으므로 기기 내 호출자가 맞춤 잠재고객 유지하는 요인을 추가로 제어한다는 점입니다.

fetchUri는 구매자가 운영하는 서버 엔드포인트를 가리켜야 하며, 이 엔드포인트는 여기에 표시된 형식과 일치하는 맞춤 잠재고객 JSON 객체를 반환합니다.

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

API 측에서 이 문제를 해결하는 방법에 관한 자세한 내용은 CA 참여 위임을 위한 설계 제안을 참고하세요.

테스트

클라이언트 코드 내에 가져오기 호출을 구현하고 맞춤 잠재고객 데이터를 반환하도록 DSP 측에 엔드포인트를 설정한 후 맞춤 잠재고객 참여 위임을 테스트할 수 있습니다. 앱을 실행하기 전에 테스트 설정 페이지에서 명령어를 실행해야 합니다. 이러한 명령어를 실행하면 Fetch API를 사용하여 호출을 시작할 수 있습니다.

이 흐름의 예를 확인할 수 있도록 GitHub의 개인 정보 보호 샌드박스 샘플 저장소에 가져오기 호출이 추가되었습니다.

맞춤 잠재고객에 직접 참여

맞춤 잠재고객을 만들고 참여하는 데 필요한 모든 정보가 이미 있다면 비동기식 Protected Audience API 호출을 사용하여 직접 만들고 참여할 수 있습니다. 맞춤 잠재고객을 직접 만들거나 참여하려면 다음 단계를 따르세요.

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

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

// Minimal initialization of a CustomAudience object
val audience: 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()

// 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);

// Minimal initialization of a CustomAudience object
CustomAudience audience = 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();

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

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

joinCustomAudience() 결과 처리

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

• onResult() 콜백은 맞춤 잠재고객을 성공적으로 생성했거나 업데이트했음을 나타냅니다.
• onError() 콜백은 두 가지 가능한 조건을 나타냅니다.
  • JoinCustomAudienceRequest가 잘못된 인수로 초기화되면 AdServicesException은 IllegalArgumentException을 원인으로 표시합니다.
  • 그 외 모든 오류에서는 IllegalStateException이 원인으로 표시된 AdServicesException을 수신하게 됩니다.

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

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() 메서드를 호출합니다.

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

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

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

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