From 905933a9063bdc8e92cd659a2d6db487427d8f7f Mon Sep 17 00:00:00 2001 From: Bryan Szekely <49168870+bszekely1@users.noreply.github.com> Date: Thu, 15 Apr 2021 19:59:07 -0400 Subject: [PATCH] Prebid mobile user ID Support (#2875) * removed sizes from RP bid params * added interstitial page and config to adUnit * interstitial page corrections * Update InterstitialAds.md * Update InterstitialAds.md * modified sidebar link * Prebid Mobile: added User ID support Co-authored-by: MartianTribe --- _data/sidebar.yml | 8 - .../android/pbm-targeting-params-android.md | 145 ++++++++++++++++++ .../pbm-api/ios/pbm-targeting-ios.md | 143 +++++++++++++++++ 3 files changed, 288 insertions(+), 8 deletions(-) diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 3f4ea8a868..8219b1f587 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -506,14 +506,6 @@ sectionTitle: subgroup: 8 -- sbSecId: 1 - title: Interstitial Ads - link: /features/interstitialAds.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 8 - - sbSecId: 1 title: Timeouts link: /features/timeouts.html diff --git a/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md b/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md index f299f4ad67..2efb32c4d7 100755 --- a/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md +++ b/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md @@ -369,6 +369,151 @@ TargetingParams.setSubjectToCOPPA(true); ``` +## User Identity + +Prebid SDK supports two interfaces to pass / maintain User IDs and ID vendor details: +* Real-time in Prebid SDK's API field setExternalUserIds +* Store User Id(s) in local storage + +Any identity vendor's details in local storage will be sent over to Prebid Server as is, unadulterated. If data is sent in the API and entered into local storage, the API detail will prevail. + +### Prebid SDK API Access + +Prebid SDK supports passing an array of UserID(s) at auction time ing the field setExternalUserIds, that is globably scopped. It is sufficient enough to set the externalUserIdArray object once per user session, as these values would be used in all consecutive ad auctions in the same session. + + +```java +/** +* List containing objects that hold External UserId parameters for the current application user. * @param externalUserIds +*/ +public static void setExternalUserIds(List externalUserIds){ + PrebidMobile.externalUserIds = externalUserIds; +} +/** +* Returns the List that hold External UserId parameters for the current application user * @@return externalUserIds as Array. +*/ +public static List getExternalUserIds() { + return PrebidMobile.externalUserIds; +``` + + +*Exmaple*: + +Java +```java +// User Id from External Third Party Sources +ArrayList externalUserIdArray = new ArrayList<>(); +externalUserIdArray.add(new ExternalUserId("adserver.org", "111111111111", null, new HashMap() { + { + put ("rtiPartner", "TDID"); + } + +})); +externalUserIdArray.add(new ExternalUserId("netid.de", "999888777", null, null)); +externalUserIdArray.add(new ExternalUserId("criteo.com", "_fl7bV96WjZsbiUyQnJlQ3g4ckh5a1N", null, null)); +externalUserIdArray.add(new ExternalUserId("liveramp.com", "AjfowMv4ZHZQJFM8TpiUnYEyA81Vdgg", null, null)); +externalUserIdArray.add(new ExternalUserId("sharedid.org", "111111111111", 1, new HashMap() { + { + put("third", "01ERJWE5FS4RAZKG6SKQ3ZYSKV"); + } + +})); +//Set External User ID +PrebidMobile.setExternalUserIds(externalUserIdArray); +``` + + +### Local Storage + +Prebid SDK provides a local storage interface to set, retrieve or update an array of user IDs with associated identity vendor details. Prebid SDK will retrieve and pass User IDs and ID vendor details to PBS if values are present in local storage. The main difference between the Prebid API interface and the local storage interface is the persistence of storage of data. Local Storage data will persist across user sessions whereas the Prebid API interface (setExternalUserIds) persists only for the user session. If a vendor's details are passed both in local storage and the Prebid API at the same time, the Prebid API data (setExternalUserIds) will prevail. + +Prebid SDK Provides five functions to handle User ID details: +* storeExternalUserId +* fetchStoredExternalUserId +* fetchStoredExternalUserIds +* removeStoredExternalUserId +* removeStoredExternalUserIds + + +```java +/** +* Use this API for storing the externalUserId in the SharedPreference +* @param externalUserId the externalUserId instance to be stored in the SharedPreference +* */ +public static void storeExternalUserId(ExternalUserId externalUserId) { + if (externalUserId != null) { + StorageUtils.storeExternalUserId(externalUserId); + } + + else { + LogUtil.e("Targeting", "External User ID can't be set as null"); + } + +} + +/** +* Returns the stored (in the SharedPreference) ExternalUserId instance for a given source +* @param source +* */ +public static ExternalUserId fetchStoredExternalUserId(@NonNull String source) { + if (!TextUtils.isEmpty(source)) { + return StorageUtils.fetchStoredExternalUserId(source); + } + + return null; +} + +/** +* Returns the stored (in the SharedPreferences) External User Id list +* */ +public static List fetchStoredExternalUserIds() { + return StorageUtils.fetchStoredExternalUserIds(); +} + +/** +* Removes the stored (in the SharedPreference) ExternalUserId instance for a given source +* @param source +* */ +public static void removeStoredExternalUserId(@NonNull String source) { + if (!TextUtils.isEmpty(source)) { + StorageUtils.removeStoredExternalUserId(source); + } + +} + +/** +* Clear the Stored ExternalUserId list from the SharedPreference +* */ +public static void removeStoredExternalUserIds() { + StorageUtils.removeStoredExternalUserIds(); +} + +``` + +*Examples* + +```java +//Set External User ID +TargetingParams.storeExternalUserId(new ExternalUserId("sharedid.org", "111111111111", 1, new HashMap() { + { + put ("third", "01ERJWE5FS4RAZKG6SKQ3ZYSKV"); + } + +})); + +//Get External User ID +ExternalUserId externalUserId = TargetingParams.fetchStoredExternalUserId("sharedid.org"); + +//Get All External User IDs +List externalUserIdList = TargetingParams.fetchStoredExternalUserIds(); + +//Remove External UserID +TargetingParams.removeStoredExternalUserId("adserver.org"); + +//Remove All External UserID +TargetingParams.removeStoredExternalUserIds(); +``` + ## Further Reading - [Prebid Mobile API - Android]({{site.baseurl}}/prebid-mobile/pbm-api/android/pbm-api-android.html) diff --git a/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md b/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md index 334587b370..4343348fcb 100644 --- a/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md @@ -493,6 +493,149 @@ Objective C Targeting.shared.subjectToCOPPA = true; ``` +## User Identity + +Prebid SDK supports two interfaces to pass / maintain User IDs and ID vendor details: +* Real-time in Prebid SDK's API field externalUserIdArray +* Store User Id(s) in local storage + +Any identity vendor's details in local storage will be sent over to Prebid Server as is, unadulterated. If data is sent in the API and entered into local storage, the API detail will prevail. + +### Prebid SDK API Access + +Prebid SDK supports passing an array of UserID(s) at auction time ing the field externalUserIdArray, that is globably scopped. It is sufficient enough to set the externalUserIdArray object once per user session, as these values would be used in all consecutive ad auctions in the same session. + + +```swift +public var externalUserIdArray = [ExternalUserId]() +``` + + +**Exmaples** + +SWIFT +```swift +// User Id from External Third Party Sources +var externalUserIdArray = [ExternalUserId]() +externalUserIdArray.append(ExternalUserId(source: "adserver.org", identifier: "111111111111", ext: ["rtiPartner" : "TDID"])) +externalUserIdArray.append(ExternalUserId(source: "netid.de", identifier: "999888777")) +externalUserIdArray.append(ExternalUserId(source: "criteo.com", identifier: "_fl7bV96WjZsbiUyQnJlQ3g4ckh5a1N")) +externalUserIdArray.append(ExternalUserId(source: "liveramp.com", identifier: "AjfowMv4ZHZQJFM8TpiUnYEyA81Vdgg")) +externalUserIdArray.append(ExternalUserId(source: "sharedid.org", identifier: "111111111111", atype: 1, ext: ["third" : "01ERJWE5FS4RAZKG6SKQ3ZYSKV"])) +Prebid.shared.externalUserIdArray = externalUserIdArray +``` + + +Objective-C +```objective_c +// User Id from External Third Party Sources +NSMutableArray *externalUserIdArray = [[NSMutableArray alloc] init]; +[externalUserIdArray addObject:[[ExternalUserId alloc]initWithSource:@"adserver.org" identifier:@"111111111111" atype:nil ext:@{@"rtiPartner" : @"TDID"}]]; +[externalUserIdArray addObject:[[ExternalUserId alloc]initWithSource:@"netid.de" identifier:@"999888777" atype: nil ext:nil]]; +[externalUserIdArray addObject:[[ExternalUserId alloc]initWithSource:@"criteo.com" identifier:@" _fl7bV96WjZsbiUyQnJlQ3g4ckh5a1N" atype:nil ext:nil]]; +[externalUserIdArray addObject:[[ExternalUserId alloc]initWithSource:@"liveramp.com" identifier:@" AjfowMv4ZHZQJFM8TpiUnYEyA81Vdgg" atype:nil ext:nil]]; +[externalUserIdArray addObject:[[ExternalUserId alloc]initWithSource:@"sharedid.org" identifier:@"111111111111" atype:[NSNumber numberWithInt:1] ext:@{@"third" : @"01ERJWE5FS4RAZKG6SKQ3ZYSKV"}]]; +Prebid.shared.externalUserIdArray = externalUserIdArray; +``` + +### Local Storage + +Prebid SDK provides a local storage interface to set, retrieve or update an array of user IDs with associated identity vendor details. Prebid SDK will retrieve and pass User IDs and ID vendor details to PBS if values are present in local storage. The main difference between the Prebid API interface and the local storage interface is the persistence of storage of data. Local Storage data will persist across user sessions whereas the Prebid API interface (externalUserIdArray) persists only for the user session. If a vendor's details are passed both in local storage and the Prebid API at the same time, the Prebid API data (externalUserIdArray) will prevail. + +Prebid SDK Provides five functions to handle User ID details: +* storeExternalUserId +* fetchStoredExternalUserIds +* fetchStoredExternalUserId +* removeStoredExternalUserId +* removeStoredExternalUserIds + + +```swift +/** +* This method allows to save External User Id in the User Defaults +*/ +public func storeExternalUserId(_ externalUserId: ExternalUserId) { + if let index = externalUserIds.firstIndex(where: { + $0.source == externalUserId.source + }) + + { + externalUserIds[index] = externalUserId + } + + else{ + externalUserIds.append(externalUserId) + } + + StorageUtils.setExternalUserIds(value: externalUserIds) +} +/** +* This method allows to get All External User Ids from User Defaults +*/ +public func fetchStoredExternalUserIds()->[ExternalUserId]? { + return StorageUtils.getExternalUserIds() +} +/** +* This method allows to get External User Id from User Defaults by passing respective 'source' string as +param */ +public func fetchStoredExternalUserId(_ source : String)->ExternalUserId? { + guard let array = StorageUtils.getExternalUserIds(), let externalUserId = array.first(where: { + $0.source + == source + }) + + else{ + return nil + } + + return externalUserId +} +/** +* This method allows to remove specific External User Id from User Defaults by passing respective 'source' +string as param +*/ +public func removeStoredExternalUserId(_ source : String) { + if let index = externalUserIds.firstIndex(where: { + $0.source == source + }) + + { + externalUserIds.remove(at: index) + StorageUtils.setExternalUserIds(value: externalUserIds) + } + +} +/** +* This method allows to remove all the External User Ids from User Defaults +*/ +public func removeStoredExternalUserIds() { + if var arrayExternalUserIds = StorageUtils.getExternalUserIds(){ + arrayExternalUserIds.removeAll() StorageUtils.setExternalUserIds(value: arrayExternalUserIds) + } + +} +``` + +**Examples** + +```swift +//Set External User ID +Targeting.shared.storeExternalUserId(ExternalUserId(source: "sharedid.org", identifier: "111111111111", atype: 1, ext: ["third" : "01ERJWE5FS4RAZKG6SKQ3ZYSKV"])) + +//Get External User ID +let externalUserIdSharedId = Targeting.shared.fetchStoredExternalUserId("sharedid.org") + +//Get All External User IDs +let externalUserIdsArray = Targeting.shared.fetchStoredExternalUserIds() + +//Remove External UserID +Targeting.shared.removeStoredExternalUserId("sharedid.org") + +//Remove All External UserID +Targeting.shared.removeStoredExternalUserIds() +``` + + ## Further Reading - [Prebid Mobile API - iOS](/prebid-mobile/pbm-api/ios/pbm-api-ios.html)