Support for First Party Data

[yoalex5]

GitHub issue #131

//ACL block

1. Access Control List

TargetingParams API:

void addBidderToAccessControlList(String bidderName)
void removeBidderFromAccessControlList(String bidderName)
void clearAccessControlList()

Example:

TargetingParams.addBidderToAccessControlList(TargetingParams.BIDDER_NAME_RUBICON_PROJECT);

OpenRTB request:

"ext": {
	"prebid": {
		"data": {
			"bidders": [
				"rubicon"]
		}
	}
}

//data block
2. global user data

TargetingParams API:

void addUserData(String key, String value)
void updateUserData(String key, Set<String> value)
void removeUserData(String key)
void clearUserData()

Example:

TargetingParams.addUserData("globalUserDataKey1", "globalUserDataValue1");

OpenRTB request:

"user": {
	"ext": {
		"data": {
			"globalUserDataKey1": [
				"globalUserDataValue1"]
		}
	}
}

3. global context data

TargetingParams API:

void addContextData(String key, String value)
void updateContextData(String key, Set<String> value)
void removeContextData(String key)
void clearContextData()

Example:

TargetingParams.addContextData("globalContextDataKey1", "globalContextDataValue1");

OpenRTB request:

"app": {
	"ext": {
		"data": {
			"globalContextDataKey1": [
				"globalContextDataValue1"]
		}
	}
}

4. adunit context data

AdUnit API:

void addContextData(String key, String value)
void updateContextData(String key, Set<String> value)
void removeContextData(String key)
void clearContextData()

Example:

adUnit.addContextData("adunitContextDataKey1", "adunitContextDataValue1");

OpenRTB request:

"imp": [{
	"ext": {
		"context": {
			"data": {
				"adunitContextDataKey1": [
					"adunitContextDataValue1"]
			}
		}
	}
}]

5. global context keywords

TargetingParams API:

void addContextKeyword(String keyword)
void addContextKeywords(Set<String> keywords)
void removeContextKeyword(String keyword)
void clearContextKeywords()

Example:

TargetingParams.addContextKeyword("globalContextKeywordValue1");
TargetingParams.addContextKeyword("globalContextKeywordValue2");
TargetingParams.addContextKeyword("globalContextKeywordValue3");

OpenRTB request:

"app": {
    "keywords": "globalContextKeywordValue1,globalContextKeywordValue2,globalContextKeywordValue3"
}

6. global user keywords

TargetingParams API:

void addUserKeyword(String keyword)
void addUserKeywords(Set<String> keywords)
void removeUserKeyword(String keyword)
void clearUserKeywords()

Example:

TargetingParams.addUserKeyword("globalUserKeywordValue1");
TargetingParams.addUserKeyword("globalUserKeywordValue2");
TargetingParams.addUserKeyword("globalUserKeywordValue3");

OpenRTB request:

"user": {
    "keywords": "globalUserKeywordValue1,globalUserKeywordValue2,globalUserKeywordValue3"
}

7. adunit context keywords

AdUnit API:

void addContextKeyword(String keyword)
void addContextKeywords(Set<String> keywords)
void removeContextKeyword(String keyword)
void clearContextKeywords()

Example:

adUnit.addContextKeyword("adunitContextKeywordValue1");
adUnit.addContextKeyword("adunitContextKeywordValue2");
adUnit.addContextKeyword("adunitContextKeywordValue3");

OpenRTB request:

"imp": [{
    "ext": {
        "context": {
            "keywords": "adunitContextKeywordValue1,adunitContextKeywordValue2,adunitContextKeywordValue3"
        }
    }
}]

Deprecated API
AdUnit. userKeywords was marked as deprecated, because this parameter creates user.keywords object.
Since global user keywords API has been added in this PR and it brings the functionality to work with userKeywords on global level hence I have added a compatibility function to create user.keywords object.
AdUnit.UserKeyword uses TargetingParams.UserKeyword inside. The parameter key will be omitted

android_all_cahnges.zip

[avohraa]

I have added a few comments/questions/suggestions. Kindly have a look at it.

[yoalex5]

@avohraa, I have added changes with you proposals.
Could you please check them?

[anwzhang]

@yoalex5

• Prebid Server only pass these data through right, it's up to the bidders how they consume it?
• If a publisher calls TargetingParams.addUserData("bidders", "randomdata") it would corrupt the data from addBidderToAccessControlList?

[yoalex5]

@anwzhang

Prebid Server only pass these data through right, it's up to the bidders how they consume it?

If take a look at a request from PS to a bidder you will see that PS sends data to the bidder from Access Control List. @bszekely1 knows more about it

If a publisher calls TargetingParams.addUserData("bidders", "randomdata") it would corrupt the data from addBidderToAccessControlList?

TargetingParams.addUserData("bidders", "randomdata"); will create:

"user": {
    "ext": {
        "data": {
            "bidders": ["randomdata"]
        }
    }
}

TargetingParams.addBidderToAccessControlList("rubicon"); will create:

"ext": {
    "prebid": {
        "data": {
            "bidders": ["rubicon"]
        }
    }
}

[bszekely1]

Prebid Server only pass these data through right, it's up to the bidders how they consume it?

This solution for First Party Data is a common method of passing FPD to all adapters, by way of the ACL. To answer your question yes, each adapter will need to read from an internal data structure to consume it.

As a goal of Prebid in general, we are working towards having an externally (publisher facing) method to pass common features for each bidder. This iteration we are integrating FPD and will attempt to follow OpenRTB like attributes wherever possible.

If a publisher calls TargetingParams.addUserData("bidders", "randomdata") it would corrupt the data from addBidderToAccessControlList?

As Oleksandr has commented, you cannot corrupt the data by passing the ACL bidder list. If you do so, the solution as shown above will just treat it like first party data and pass it for adapters to consume.

[anwzhang]

@yoalex5 Can you resolve the merge conflict ?

[yoalex5]

@anwzhang I have resolved the merge conflicts

[yoalex5]

@anwzhang, could you please review it ?

[anwzhang]

I don't see necessary for this part of code.

[yoalex5]

This part of code allows us to write an elegant code like:

user.put("keywords", globalUserKeywordString);
ext.put("consent", TargetingParams.getGDPRConsentString());

instead of:

if (!TextUtils.isEmpty(finalKeywords)) {
    user.put("keywords", finalKeywords);
}
if (TargetingParams.isSubjectToGDPR() != null) {
    ext.put("consent", TargetingParams.getGDPRConsentString());
}

Step by step (during refactoring) I am going to remove redundant if (!TextUtils.isEmpty()) checks