Intent to Implement: Updates to UserSync API

[jsnellbaker]

Type of issue

Feature

Description

In order to offer additional features to the UserSync functionality, we plan to implement some changes to the API. This includes adding and removing existing fields which make break current setups. Below is a pair of lists of the new and deprecated fields, with an explanation of the functional changes further below.

This will require some adapters to update their getUserSyncs code in case they were referring to deprecated fields.

API changes

New fields

• filterSettings: {config}

Deprecated fields

• iframeEnabled: bool
• pixelEnabled: bool
• enabledBidders: []

All other API fields that exist today and not listed here would remain and retain their existing functionality.

Functional changes

Currently the only filtering field available is the enabledBidders field. This field takes a list of bidders and acts as a white-list, allowing only those listed bidders to drop their iframe and image pixels. Additionally the iframe pixels are only dropped if they've also included the iframeEnabled field in the config and set it to true.

The proposed changes will offer the following:

• the filterSettings field will accept an object config that allows the publisher to set a white-list or black-list filter against a list of bidders.
• distinct bidder filters can be set for the iframe or image pixels (so that you can have black-list on pixels and a white-list on iframes)
• implicitly listing the iframe object in this config automatically enables iframes pixels to drop (removing the need to add iframeEnabled)
• not listing the image/iframe fields will have them operate in their current default modes (ie image pixels are inherently permitted for all bidders, while iframe pixels are inherently blocked for all bidders).

The filterSettings config would look like the following:

filterSettings: {
    iframe: {
        bidders: ['a', 'b'],
        filter: 'black'
    },
    image: {
        bidders: ['*'],
        filter: 'white'
    }
}

The bidders field would either accept a list of strings of the bidders or a '*' string to indicate all bidders.
The filter field is an enum that accepts either white or black to indicate which type of filtering logic should be applied for the tracking type.

As mentioned earlier, not including one of the iframe or image fields means today's default logic would be used. In case of no image object, all bidders are permitted to drop their image pixels. In case of no iframe object, no bidders are permitted to drop their iframe pixels.

If a publisher wanted to enable all bidders drop their iframe pixels, they'd need to configure the filterSettings field with an iframe object using the '*' and white filter option.

[bretg]

The new design is fine, but would prefer the terms "include" and "exclude" over "white" and "black".

More importantly, we need to keep the old functionality around -- breaking changes need to be avoided, IMO... 1.0 was enough. That said, we can provide a mapping between the old interface and the new pretty easily. e.g.

if iframeEnabled=true, treat as if it were

iframe: {
        bidders: [array from enabledBidders or all bidders if not specified]
        filter: 'include'
    }

Similar for if pixelEnabled=true:

image: {
        bidders: [array from enabledBidders or all bidders if not specified]
        filter: 'include'
    }

[bretg]

@mkendall07, @jsnellbaker - any thoughts on backwards compatibility?

[jsnellbaker]

adding @mjacobsonny as well to share his thoughts.

[mkendall07]

I'm fine with what @bretg proposed and we can "soft" deprecate the old methods / update our examples to use the new filter options.

Soft deprecations can be removed as part of the next major release (i.e. 2.x)

[jsnellbaker]

@bretg when preserving the old fields (eg enabledBidders) should we automatically trump their native logic if the new field is also present?

eg if a publisher had a setup like the following:

{
  iframeEnabled: true,
  enabledBidders: ['a', 'b'],
  filterSettings: {
    iframe: {
      bidders: ['a', 'c'],
      filter: 'exclude'
    }
  }
}

Should we:

• only consider the logic that comes from the filterSettings object and ignore any intended logic from the enabledBidders field?
• try to mix/match the two by (in this case): blacklisting the bidders for iframe pixels but whitelist the bidders from the enabledBidders for image pixels?
• reject this setup entirely due to conflicting logic?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.