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 <[email protected]>
prebid · Apr 15, 2021 · 905933a · 905933a
1 parent b93b5b6
commit 905933a
Show file tree

Hide file tree

Showing 3 changed files with 288 additions and 8 deletions.
diff --git 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
@@ -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<ExternalUserId> externalUserIds){
+    PrebidMobile.externalUserIds = externalUserIds;
+}
+/**
+* Returns the List that hold External UserId parameters for the current application user * @@return externalUserIds as Array.
+*/
+public static List<ExternalUserId> getExternalUserIds() {
+    return PrebidMobile.externalUserIds;
+```
+
+
+*Exmaple*:
+
+Java
+```java
+// User Id from External Third Party Sources
+ArrayList<ExternalUserId> 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<ExternalUserId> 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<ExternalUserId> 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
@@ -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<ExternalUserId *> *externalUserIdArray = [[NSMutableArray<ExternalUserId *> 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)