ऑडियंस डेटा तय करना

कस्टम ऑडियंस, उपयोगकर्ताओं के ऐसे ग्रुप को कहते हैं जिनकी दिलचस्पी या इरादे एक जैसे होते हैं. इन्हें विज्ञापन देने वाले व्यक्ति या कंपनी का ऐप्लिकेशन तय करता है. कोई ऐप्लिकेशन या SDK टूल, कस्टम ऑडियंस का इस्तेमाल करके किसी खास ऑडियंस के बारे में बता सकता है. जैसे, वह व्यक्ति जिसने शॉपिंग कार्ट में आइटम छोड़ दिए हैं.

Android Protected Audience API का इस्तेमाल, उपयोगकर्ता के डिवाइस पर कस्टम ऑडियंस में शामिल होने और उनसे बाहर निकलने के लिए किया जा सकता है. कस्टम ऑडियंस बनाने और उसमें शामिल होने के दौरान, आपके पास दो विकल्प होते हैं. पहला, किसी सर्वर को यह ज़िम्मेदारी सौंपें कि वह कस्टम ऑडियंस की कुछ या सभी प्रॉपर्टी फ़ेच करे. दूसरा, एपीआई को सीधे कॉल करते समय यह जानकारी दें.

कस्टम ऑडियंस

किसी डिवाइस पर मौजूद हर CustomAudience ऑब्जेक्ट की पहचान, यहां दिए गए पैरामीटर के कॉम्बिनेशन से की जाती है:

• owner: मालिक ऐप्लिकेशन के पैकेज का नाम. यह कॉलर ऐप्लिकेशन के पैकेज के नाम पर अपने-आप सेट हो जाता है.
• buyer: यह खरीदार के विज्ञापन नेटवर्क का आइडेंटिफ़ायर है. यह नेटवर्क, इस कस्टम ऑडियंस के लिए विज्ञापन मैनेज करता है.
• name: कस्टम ऑडियंस के लिए कोई भी नाम या आइडेंटिफ़ायर.

इसके अलावा, CustomAudience को इन ज़रूरी पैरामीटर के साथ बनाया जाना चाहिए:

• हर दिन अपडेट होने वाला यूआरएल: यह एक एचटीटीपीएस यूआरएल है. इसे हर दिन बैकग्राउंड में क्वेरी किया जाता है, ताकि कस्टम ऑडियंस के उपयोगकर्ता की बिडिंग के सिग्नल, भरोसेमंद बिडिंग डेटा, और विज्ञापनों के लिए रेंडर यूआरएल और मेटाडेटा को अपडेट किया जा सके.
• बिडिंग लॉजिक यूआरएल: यह एक एचटीटीपीएस यूआरएल होता है. विज्ञापन चुनने के दौरान, इससे क्वेरी की जाती है, ताकि खरीदार के JavaScript बिडिंग लॉजिक को फ़ेच किया जा सके. इस JavaScript में, ज़रूरी फ़ंक्शन सिग्नेचर देखें.
• विज्ञापन रेंडर करने वाले आईडी: यह आईडी, खरीदार की विज्ञापन टेक्नोलॉजी कंपनी सेट करती है. यह B&A के लिए पेलोड जनरेट करने की प्रोसेस को ऑप्टिमाइज़ करने के लिए होता है.

CustomAudience ऑब्जेक्ट के लिए वैकल्पिक पैरामीटर में ये शामिल हो सकते हैं:

• चालू होने का समय: कस्टम ऑडियंस, विज्ञापन चुनने और रोज़ाना अपडेट पाने की सुविधा का इस्तेमाल सिर्फ़ तब कर सकती है, जब वह चालू हो जाए. यह किसी ऐप्लिकेशन का इस्तेमाल बंद कर चुके लोगों को फिर से जोड़ने के लिए काम आ सकता है.
• समयसीमा खत्म होने का समय: यह वह समय होता है जिसके बाद कस्टम ऑडियंस को डिवाइस से हटा दिया जाता है.
• उपयोगकर्ता के बिडिंग सिग्नल: यह एक JSON स्ट्रिंग होती है. इसमें उपयोगकर्ता के सिग्नल शामिल होते हैं. जैसे, उपयोगकर्ता की पसंदीदा जगह. विज्ञापन चुनने की प्रोसेस के दौरान बिड जनरेट करने के लिए, खरीदार के बिडिंग लॉजिक JavaScript इसका इस्तेमाल करता है. इस फ़ॉर्मैट की मदद से, विज्ञापन टेक्नोलॉजी प्लैटफ़ॉर्म अलग-अलग प्लैटफ़ॉर्म पर कोड का फिर से इस्तेमाल कर सकते हैं. साथ ही, JavaScript फ़ंक्शन में इसका इस्तेमाल करना आसान हो जाता है.
• भरोसेमंद बिडिंग डेटा: यह एक एचटीटीपीएस यूआरएल और स्ट्रिंग की सूची होती है. इसका इस्तेमाल विज्ञापन चुनने की प्रोसेस के दौरान किया जाता है. यह भरोसेमंद Key/Value सेवा से बिडिंग सिग्नल फ़ेच करता है.
• विज्ञापन: यह AdData ऑब्जेक्ट की एक सूची होती है. ये ऑब्जेक्ट, विज्ञापन चुनने की प्रोसेस में शामिल विज्ञापनों से जुड़े होते हैं. हर AdData ऑब्जेक्ट में ये शामिल होते हैं:
  • रेंडर यूआरएल: यह एक एचटीटीपीएस यूआरएल होता है, जिसका इस्तेमाल फ़ाइनल विज्ञापन को रेंडर करने के लिए किया जाता है.
  • मेटाडेटा: यह एक JSON ऑब्जेक्ट है. इसे स्ट्रिंग के तौर पर क्रम से लगाया जाता है. इसमें ऐसी जानकारी होती है जिसका इस्तेमाल खरीदार के बिडिंग लॉजिक से किया जाता है. यह जानकारी, विज्ञापन चुनने की प्रोसेस के दौरान इस्तेमाल की जाती है.
  • विज्ञापन फ़िल्टर: यह एक क्लास है. इसमें ऐप्लिकेशन इंस्टॉल करने के विज्ञापन को फ़िल्टर करने और विज्ञापन चुनने के दौरान फ़्रीक्वेंसी कैपिंग के लिए ज़रूरी जानकारी होती है.

कस्टम ऑडियंस को फ़ेच करना और उसमें शामिल होना

fetchAndJoinCustomAudience API की मदद से, खरीदार अपने पार्टनर एमएमपी या एसएसपी के डिवाइस पर मौजूद डेटा का इस्तेमाल करके, कस्टम ऑडियंस में शामिल होने की अनुमति दे सकते हैं.

इसके लिए, डिवाइस पर मौजूद कॉलर (चाहे वह 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
      }
    }
  ]
}

एपीआई की मदद से इस समस्या को कैसे हल किया जाता है, इस बारे में ज़्यादा जानकारी के लिए Design Proposal for Join CA Delegation पढ़ें.

टेस्ट करना

क्लाइंट कोड में फ़ेच कॉल लागू करने और डीएसपी की तरफ़ से कस्टम ऑडियंस का डेटा वापस भेजने के लिए एंडपॉइंट सेट अप करने के बाद, कस्टम ऑडियंस में शामिल होने के डेलिगेशन की जांच की जा सकती है. ऐप्लिकेशन चलाने से पहले, आपको टेस्टिंग सेटअप पेज पर जाकर कमांड चलाने होंगे. इन कमांड को चलाने के बाद, आपको Fetch API का इस्तेमाल करके कॉल करने की सुविधा मिल जाएगी.

इस फ़्लो का उदाहरण देखने के लिए, GitHub पर Privacy Sandbox Samples रिपॉज़िटरी में फ़ेच कॉल जोड़े गए हैं.

सीधे तौर पर कस्टम ऑडियंस में शामिल होना

अगर आपके पास कस्टम ऑडियंस बनाने और उसमें शामिल होने के लिए ज़रूरी सभी जानकारी पहले से मौजूद है, तो सीधे तौर पर एसिंक्रोनस Protected Audience API कॉल का इस्तेमाल करके ऐसा किया जा सकता है. कस्टम ऑडियंस को सीधे तौर पर बनाने या उसमें शामिल होने के लिए, यह तरीका अपनाएं:

1. CustomAudienceManager ऑब्जेक्ट को शुरू करें.
2. CustomAudience ऑब्जेक्ट बनाएं. इसके लिए, खरीदार का पैकेज और उससे जुड़ा नाम जैसे मुख्य पैरामीटर तय करें. इसके बाद, CustomAudience ऑब्जेक्ट की मदद से JoinCustomAudienceRequest ऑब्जेक्ट को शुरू करें.
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 ऑब्जेक्ट का इस्तेमाल करता है.

• onResult() कॉलबैक से पता चलता है कि कस्टम ऑडियंस बन गई है या अपडेट हो गई है.
• onError() कॉलबैक से दो संभावित स्थितियों के बारे में पता चलता है.
  • अगर JoinCustomAudienceRequest को अमान्य आर्ग्युमेंट के साथ शुरू किया जाता है, तो AdServicesException, IllegalArgumentException को वजह के तौर पर दिखाता है.
  • अन्य सभी गड़बड़ियों के लिए, AdServicesException मिलता है. साथ ही, गड़बड़ी की वजह के तौर पर IllegalStateException दिखता है.

यहां 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 से एपीआई कॉल के खत्म होने का सिग्नल मिलता है. निजता की सुरक्षा के लिए, गड़बड़ी के नतीजे में यह नहीं बताया जाता कि गड़बड़ी अंदरूनी है या अमान्य आर्ग्युमेंट की वजह से हुई है. एपीआई कॉल पूरा होने पर, onResult() कॉलबैक को कॉल किया जाता है. भले ही, मैच करने वाली कस्टम ऑडियंस को हटाया गया हो या नहीं.