New User ID Submodule: Rewarded Interest

[thede-ri]

Type of change

• New User ID submodule

Description of change

Rewarded Interest is an identity provider that enables users to monetize and manage the exposure of their identity to various ad sources through the Rewarded Interest browser extension.

The Rewarded Interest browser extension exposes an on-page API window.__riApi.getIdentityToken(). This submodule obtains the identity token, wraps it into eid and passes it to the callback provided by the User Id module. If __riApi is not available - error will be logged (if debug is enabled) and no ID will be passed to the callback.

Note: no storage is used as Identity Token is refreshed frequently.
Rewarded Interest partners (such as DSPs, SSPs, and publishers) can use the Rewarded Interest Identity Resolution API to resolve the Identity Token into a CMAID (Consumer Mediated Advertising Identity). The CMAID is a durable, cross-site, cross-device advertising identifier that remains consistent across visits and devices enrolled by a Rewarded Interest user, unless they choose to reset or pause it.

Config example:

pbjs.setConfig({
    userSync: {
        userIds: [{
            name: "rewardedInterestId"
        }]
    }
})

[patmmccann]

why doesnt rewarded interst browser extension just inject into the eids object in place instead of relying on publisher moxule deployment?

[justadreamer]

Hi Patrick, I guess injecting it into the configuration won't do as getIdentityToken() must be called before each auction as it may return a different token each time. Also there is a synchronization issue - the API is async in nature, while the configuration is executed synchronously and may be even before the API is available on the page. Injecting it into the raw requests seems a bit brutal, so publishing it as a module seems like a good way for publishers to opt-in.

[justadreamer]

So in general the extension can indeed attempt to set the ortb2.user.ext.eids on page load (thanks for this suggestion!), like:

var pbjs = pbjs || {};
pbjs.que = pbjs.que || [];

pbjs.que.push(function () {
    pbjs.mergeConfig({
        ortb2: {
            user: {
                ext: {
                    eids: [
                        {
                            source: "rewardedinterest.com",
                            uids: [
                                {
                                    id: "<IdentityToken>",
                                    atype: 3
                                }
                            ]
                        }
                    ]
                },

            },
        },
    });
});

@patmmccann is this the way you meant by "inject in place"?

A couple concerns:

1. The publisher may not even expose pbjs as global (I doubt it is widespread, but still a possible modification) - for such pubs it makes sense to add a module. Also pbjs may be renamed and the extension would have to track window.__pbjsGlobals to find an appropriate object and it may be a bit problematic to sync with pbjs loading, so for this case a module may also be an appropriate solution. Unless there are some callbacks that would signal the wrapper is loaded of which we are unaware.
2. We don't have a way to guarantee that our ortb2 snippet will be merged in any particular order relative to other config snippets - thus we can be easily overwritten by publisher's setConfig call.
3. We noticed that some bid adapters do not take stuff from ortb2.user.ext.eids, unless there is also at least one ID submodule that added its stuff into bidRequest.userIdAsEids - these might need to be patched as separate pull requests ofc.

Thus the module adds some additional reliability.

[patmmccann]

@patmmccann is this the way you meant by "inject in place"?

yeah that's what i meant, you'll get a lot more uptake that way :) you are of course welcome to do both, but i think the injection path will be more successful

Also pbjs may be renamed and the extension would have to track window.__pbjsGlobals to find an appropriate object and it may be a bit problematic to sync with pbjs loading,

that's fairly easy to handle, you can just inject into all the prebid globals you find :)

We noticed that some bid adapters do not take stuff from ortb2.user.ext.eids, unless there is also at least one ID submodule that added its stuff into bidRequest.userIdAsEids - these might need to be patched as separate pull requests ofc.

I think this was solved in #12110 ; if not, we should open an issue. Cc @dgirardi

[justadreamer]

Thank you, Patrick; that’s a great tip! We would still suggest merging the submodule to address two key points:

1. If the publisher does not globally expose any pbjs instances — possibly due to a custom wrapper build — the extension won’t be able to inject the ID. In such cases, the publisher may still want to integrate the submodule. Additionally, the injection behavior could be made optional subject to the user choice, thus enabling only those publishers who integrate the submodule to pass the ID.

2. Since the extension injects values into the Prebid.js configuration, it would be beneficial to document this behavior. A suitable place for this documentation could be the submodule documentation, ensuring clarity around this functionality and setting expectations.

Re: #12110 - it looks like currently userIdAsEids is created in User ID module and will be merged with ortb2.user.ext.eids only if at least one user ID submodule was configured. We can add a patch to create an empty userIdAsEids and merge stuff ortb2.user.ext.eids even if 0 submodules are added. It still requires that publisher adds a User ID module. However only several bid adapters seem to not check ortb2.user.ext.eids and only look at userIdAsEids, f.e. rubicon - so they can also be patched individually.