TECH DOCS
USAGE OF THE FIRST-ID IDENTIFIER
Now that you've implemented the first-id solution, you'll probably need to pass it on to certain advertising partners or internal tools. Here are just a few examples of frequent integrations. If you have any questions, don't hesitate to contact us at support@first-id.fr
⚠️ IMPORTANT ⚠️
the code provided on these pages is provided "as is", without warranty of any kind, either express or implied. In no event will First-id be liable for any claims, damages, updates or other liabilities. It is your responsibility to ensure that the code you use works properly on your media.
⚠️ IMPORTANT ⚠️
it is important to get in touch with your first-id contact before sending the identifier to an external partner that is not covered by the terms of your first-id contract.
How to retrieve the first-id value
💡 TIP : You can use our SDK to simplify first-id retrieval. See the doc
First-id is stored in a first-party cookie, so you can easily retrieve its value for use in any future third-party integration, such as a DMP, google PPID, identity prebid modules, etc. We list below the integrations you may need.
Here's some basic javascript code you can adapt to your liking, which will return the value of the first-id cookie in your browser's console:
const GetCookie = {
get: name => {
let pattern = new RegExp(`(?:(?:^|.*; *)${name} *= *([^;]*).*$)|^.*$`, 'i');
let c = document.cookie.match(pattern)[1];
if (c) return decodeURIComponent(c);
}
}
console.log("My First-id ==> " + GetCookie.get('firstid'));
FOR USE IN YOUR ADSERVER
Your Adserver is Google Ad Manager : Google PPID
⚠️ IMPORTANT ⚠️
it's important to contact your Google contact before sending the ppid identifier, as this may be subject to contractual obligations on the part of the adserver.
The value of the first-id cookie can be passed to the Google PPID if you use GAM as an adserver.
Please refer to the official Google support documentation for more information and integration details.
for web sites, use the following methos PublisherProvidedId :
in your Google Publisher Tag implementation, you need to add this function googletag.pubads().setPublisherProvidedId as described in the example below with the cookie value first-id
<script type = "text/javascript" >
googletag.pubads().setPublisherProvidedId('650349c9714c95f857f63dbd089683c3');
googletag.enableServices();
</script>
Details for the method pubService
pubService.setPublisherProvidedId(identifier)
This method defines the values of the Provided ID publisher, which is used for capping and audience-based activities in GAM.
Parameters :
string identifier: An alphanumeric ID supplied by the editor with a maximum number of 150 characters (32 for first-id).
💡 TIP : If you are using a video player with the IMA html5 SDK, please refer to this Google support documentation to pass the First-id cookie value to the SDK.
💡 TIP : Installing/using our notre SDK can greatly simplify the process of retrieving the first-id identifier and passing it on to your adserver.
Your Adserver is Google Ad Manager : Secure signals
First-id can also be shared with the SSPs you are using in your Open bidding setup and/or with Authorized buyers
1 - Allow secure signal sharing
Complete the following steps to allow secure signal sharing:
> Sign in to Google Ad Manager.
> Click Admin, then Global settings, and then Ad exchange account settings.
> In the "Secure signal sharing" section, click the toggle on On to allow secure signal sharing. To disable secure signal sharing, click the toggle off off disable.
2 - Allow first-id to share secure signals
> Click Inventory, then Secure signals. A table shows the secure signals you can share. Toggle First-id on
> Click Save.
3 - Select bidders to share secure signals
> Click Delivery, then Bidders.
> Select Authorized buyers and/or Open Bidding.
> Click the name of the bidder.
> For Open Bidding, click Settings.
> Turn on the Allow secure signal sharing toggle On.
> Click Save.
The bidder can now receive the secure signals you share with them. Bidders can choose whether they want to receive a signal when it's available.
💡 TIP : Please refer to the official Google support documentation for more information and integration details.
Your Adserver is Xandr : Xandr PPID (alpha)
⚠️ IMPORTANT ⚠️
it's important to get in touch with your Microsoft advertising contact before sending the ppid identifier, as this may be subject to contractual obligations on the part of the adserver.
The first-id cookie value can be passed to your adserver implementation via the Xandr PPID if you use Xandr as an adserver.
Please refer to the xandr official support documentation for more information and integration details.
In the specific case of first-id, here's what the optional Xandr tag parameter should look like:
apntag.setPageOpts({
member: 958,
user: {
age: 25,
externalUid: '10',
userIds: [
{
"type": "extendedIDs",
"eids": [{
"id": "650349c9714c95f857f63dbd089683c3",
"source": "first-id.fr"
}]
}, // publisher first party IDs
],
💡 TIP : Installing/using our notre SDK can greatly simplify the process of retrieving the first-id identifier and passing it on to your adserver.
Your Adserver is Google Ad Manager : onboarding Audiences based on first-id
If First-id is used in your DMP to onboard audience segments, your DMP can sync your first-party data segments directly to GAM so that they are directly available for targeting in the GAM UX in the custom targeting / audience segment section of the campaigns.
this will allow to use the first-id within the ppid feature of GAM to control cookieless frequency capping for your direct campaigns as well as use the id as a persistent signal in your adx programmatic deals.
you should get in touch with your google account manager to be able to use this features, as well as your contact within your DMP to make sure they are able to sync segments with the first-id that they ingested.
💡 TIP : Please refer to this official Google support documentation article for more information and integration details.
Your Adserver is Equativ : Extended user Identification
⚠️ IMPORTANT ⚠️
it's important to get in touch with your Equativ contact before sending the first-id as this may be subject to specific integrations or activations , like DMP api onboarding, or capping based on extended ids
💡 NOTE : Please note that this article is a narrowed, first-id contectualized version of this more complete article on Equativ knowledge base
To embrace the cookieless user identification era, Equativ follows the Extended Identifiers (eids) specification (see IAB OpenRTB 3.0 specification and IAB AdCOM v1.0 specification). Extended Ids are sometimes referred to as "alternative Ids".
At this time, Equativ supports extended Ids as follows:
-
publishers can sign up with a supported user identification provider and send the user Ids in ad calls to Equativ’s system; see list of supported providers below in chapter “Logging”
-
Equativ logs the presence of a user Id from a supported provider in the ad call and makes it available in the Reporting API as an additional dimension; extended Id statistics are not yet available in the Equativ Monetization Platform
-
Smart forwards all eids received in the ad calls to the DSPs in the bid requests as shown in this example:
{ "user": {
"ext": {
"eids": [{
"source": "first-id.fr",
"uids": [{"id": "c61f9ef05a94c77d9c3bddb7ab6fb2ed"
The list below indicates if your type of integration with Equativ is compatible with first-id :
Web integration :
-
smart.js library
-
Video plugin
-
Embedded ad Manager
-
Standalone Vast request
-
Connected TV
-
Adressable TV
Header bidding Integration :
-
Prebid.js
-
Prebid Server
-
Holistic+
-
Managed holistic+
Server to Server :
-
Post Ad API
-
Get Ad API
Sending first-id as extended Ids in web environments (smart.js)
You can send extended Ids in web environments where Equativ's "smart.js" library is used (more details about the library in the Tagging guide). This section describes the manual setup of the transfer. For the automated transfer, see previous section.
In case of the manual transfer, extended Ids are sent using the method sas.setEids(eids), which is available for both Generic POST and OneCall POST requests. The structure of the eids must follow the IAB's AdCOM 1.0 specification.
Payloads can be base64 encoded (see example below).
The sas.setEids(eids), method must be called before the actual ad request is sent - for more details, get back to the user identification provider.
Example OneCall POST :
sas.cmd.push(function () {
sas.setEids([
{
source: "first-id.fr",
uids: [
{
atype: 1,
id: "c61f9ef05a94c77d9c3bddb7ab6fb2ed", //First-id token
ext: {
linkType: 0
}
}
]
},
]);
});
sas.cmd.push(function () {
sas.call("onecall", {
siteId: 317777,
pageId: 1232599,
formats: [{
id: 84313,
tagId: "sas_tag_001"
}],
target: 'iid=9448189'
});
});
</script>
//Call this method as soon as the values are available from first-id
sas.cmd.push(function () {
sas.setEids([
{
source: "first-id.fr",
uids: [
{
atype: 1,
id: "c61f9ef05a94c77d9c3bddb7ab6fb2ed", //First-id token
ext: {
linkType: 0
}
}
]
},
]);
});
sas.cmd.push(function () {
sas.call("std", {
siteId: 317777,
pageId: 1232599,
formatId: 84313,
tagId: 'sas_tag_001',
target: 'iid=9448189'
});
});
</script>
Example Generic POST :
Sending extended Ids in Holistic+ integrations
A Holistic+ integration consists in a competition of direct campaigns, bids from Equativ's demand partners as well as bids from header bidding - the highest CPM wins the competition.
The configuration of prebid.js is done client-side:
-
implement and configure the User ID Module provided by prebid.js
-
retrieve the eid object using the pbjs.getUserIdsAsEids() method from prebid.js
-
call sas.setEids() from smart.js with the eid object that was just retrieved from prebid.js (for more details, see chapter "Sending extended Ids in web environments (smart.js)" above
Sending extended Ids in Managed Holistic+ integrations
A Managed Holistic+ integration is similar to Holistic+ integrations (see previous chapter) but the administration of prebid.js is done directly in the Managed Holistic+ UI provided by Equativ.
The setup in the UI is explained in chapter "User ID configuration" in the Managed Holistic+ article.
Note that the extended Ids are sent to Equativ automatically using the sas.setEids() method (there are no further manual steps required).
Sending extended ids with Equativ's video plugin
Read the according technical documentation (chapter "Extended user identification options") which also provides a sample of the eids JSON configuration.
Sending extended Ids in DMP integrations
Equativ supports one preferred extended Id provider per DMP; please get back to your contact at Equativ and indicate the provider whose extended Ids (alternative Ids) you intend to use; more details in DMP Integration API
Logging
Equativ logs the presence of a provider’s user id in the ad request with this form.
-
the provider as sent in the source field (see "Sending extended ids with OneCall" above) : first-id.fr
-
the provider name : First ID
-
the Id Equativ assigns to the provider : 35
Frequency capping based on extended Ids
By default, frequency capping is implemented with a cookie (cookie name: pid) that contains a unique user id to identify the user (more details about frequency capping here).
Since third party cookies are increasingly blocked by browsers, Equativ also supports frequency capping based on extended ids.
⚠️ This feature requires activation in your network - please reach out to your contact at Equativ to have it enabled. Note that only one provider can be enabled per customer network to be used as an alternative to cookie based frequency capping.
Once the provider is enabled in your network, Equativ will use this provider's ids to implement frequency capping whenever an ad call does not contain any user id from the pid cookie nor any user id sent through the uid parameter (more details about the uid parameter here).
Reports
To create a report, go to Reports > Create a report and scroll to the "Quality & Privacy" section:
-
Extended Ids - in programmatic reports only; indicates the extended user Ids from user identification providers that were sent in the ad call to Equativ
-
User Identity - in direct and programmatic reports; indicates the number of times a uid ("Has User Uid") / pid ("Has User Pid") was or was not sent in the ad requests to Equativ; pid is a user Id defined by Equativ and stored in a Equativ cookie called “pid”; uid is a publisher specific user Id; if a uid is present in the ad request, it overrides the pid
💡 TIP : Installing/using our notre SDK can greatly simplify the process of retrieving the first-id identifier and passing it on to your adserver.
FOR THE USE IN YOUR PREBID WRAPPER
💡 TIP : If you don't manage your own prebid wrapper, you may need to adapt your wrapper technology to correctly retrieve the first-id identifier and pass it to Prebid. We can contact your service provider to carry out the necessary developments.
PubProvidedId
⚠️ IMPORTANT ⚠️
it is important to get in touch with your first-id contact before sending the identifier to an external partner that is not covered by the terms of your first-id contract.
The PubProvided ID module enables publishers to pass a first-party ID into the bid stream of their Prebid integration. This is the preferred method for passing the first-id to prebid bidders who have agreements with First-id.
The module supports a user-defined function that generates an eids object:
Alternatively, eids values can be passed directly to the setConfig :
In both cases, the bids adapters will receive the id after the consent has been validated.
This design allows for multiple uiids in the eids object. You may already be working with other id providers, but you can include the first-id identifier in the same eids object.
the extension "source-type eids.uids.ext.stype " helps entities downstream of the bid request to identify the data. For first-id, the source-type to use is :
Bid adapters listening to userIds.pubprovidedId will not receive a string. Please use the userIdAsEids value/function to return the id as a string.
To use PubProvidedId, add it to your prebid.js package:
Configuration of PubProvidedId for first-id :
Nom | Scope | Type | Description | Example |
|---|---|---|---|---|
SSPs SPECIFIC INTEGRATIONS
FreeWheel MRM
💡 This feature requires specific enablement by FreeWheel before it is available. Please speak to your account if you wish to have it enabled for vour network
the first-id identifier is passed in the MRM ad request using the reserves key-value _fw_3P_UID
FreeWheel will pass on the id in the eids object in the bid request to the DSP.
💡FreeWheel will send the first-id identifier in bid requests using the extended identifiers specification for OpenRTB as documented here : https://github.com/InteractiveAdvertisingBureau/openrtb/blob/main/extensions/2.x_official_extensions/eids.md
the first-id identifier passed in the the reserved key-value _fw_3P_UID should be in the format "prefix:userid". this translate as :
_fw_3P_uid=firstid:c61f9ef05a94c77d9c3bddb7ab6fb2ed,prefix2:userid2
in this case the prefix is "firstid" but FreeWheel will take care of sending the correct syntax ("first-id.fr") in the user.ext.eids.source in the bid request, as well as in the user.ext.eids.rtipartner (FirstID)
FOR THE USE IN YOUR VIDEO PLAYER
Digiteka Video Player
💡 TIP : Installing/using our notre SDK can greatly simplify the process of retrieving the first-id identifier and passing it on to your adserver.
First, refer to the official Digiteka documentation for the integration of the player
you can then set the first-id value to let the player pass it to the ppid of your adserver by adding this parameter in the source url of the player iframe like in the example below :
<iframe src="//www.ultimedia.com/deliver/generic/iframe/mdtk/01173314/zone/69/showtitle/1/src/q5sxux3/ad/no/ppid/c61f9ef05a94c77d9c3bddb7ab6fb2ed"
width="534"
height="320"
allowfullscreen="true"
allow="autoplay"
referrerpolicy="no-referrer-when-downgrade"
>
</iframe>
FOR THE USE IN YOUR DMP
DMP 1plusX
💡 TIP : Installing/using our notre SDK can greatly simplify the process of retrieving the first-id identifier and passing it on to your adserver.
First, retrieve the first-id identifier using our javascript sdk (using the methods documented her)
You can then add this value to the oneplusX SDK called on your pages, which will allow 1plusX to retrieve the id :
ope("[[clientID]]", "syncIds", ["firstID:c61f9ef05a94c77d9c3bddb7ab6fb2ed"]);
💡 TIP : [clientID] must be replaced by your own publisher id supplied by 1plusX, and the value in bold by the value of the first-id identifier retrieved.
For more information on SDK integration, please see 1plusX documentation
DMP Permutive
ow to enable first-id collection via the Permutive dashboard
To see the different identifiers, follow these steps :
-
Navigate to your workspace dashboard
-
on the left, select 'Settings
-
at the top, select the 'Login' tab
To add First-id identifiers, follow these steps:
-
Navigate to dashboard > 'settings' > 'Identifiers'.
-
Select 'Add an identifier' (both red and green buttons work)
-
Add the tag for the first-id identifier. Click OK, and you're done.
Set up the JavaScript collector to route identifiers to Permutive
💡 TIP : Installing/using our notre SDK can greatly simplify the process of retrieving the first-id identifier and passing it on to your adserver.
⚠️ IMPORTANT ⚠️ This code is provided "as is", without warranty of any kind, either express or implied. In no event will Permutive or First-id be liable for any claims, damages, updates or other liabilities. It is your responsibility to ensure that the code you use works properly on your media.
Code example :
Please refer to the documentation on Permutive's website
DMP Piano
The retrieval of the first-id token in Piano's javascript for onbarding passes through the modification of the script embedded on your website.
For more information please get in touche with your contact at Piano
For referral purposes, please find the link to the documentation on Piano's website
DMP Mediarithmics
Retrieving first-id identifiers does not require any modification to the Mediarithmics integration already in place on the publisher's site. Collection is activated directly in the Mediarithmics "Navigator" interface.
To find out how to do this, please refer to the
Numberly
You should trigger the fetching of the first-id through this script after the main js tag that is in place on your page for numberly (tro.js)
this script should be implemented as a second script.
Please replace the {first_id} by the value of the first-id on the page.
var tagid = _troq.tagid;
var uid_first = _troq.uid || getCookie('__troRUID');
(new Image(1, 1)).src = 'https://mmtro.com/p?tagid='+ tagid+'&partner_name=firstid&rtgpartner_name=firstid&rtgpartner_uid={first_id}&partner_uid={first_id}&r1='+uid_first
Outbrain Widget
⚠️ IMPORTANT ⚠️
il est important de vous mettre en relation avec votre contact chez first-id avant de procéder à l'envoi de l'identifiant à un partenaire externe qui ne serait pas prévu dans les termes de votre contrat first-id
💡 TIP : If you installed our SDK the instructions below are useless since it can gather automatically fir first-id token and send it to the widget outbrain
Outbrain widgets include a data-ob-ppid parameter that you can use to pass the first-id identifier that will be recognized as such by Outbrain.
The integration looks like this:
<div class="OUTBRAIN" data-src="https://www.editor.com/urlOfThePage" data-widget-id="AR_1" data-ob-ppid="{“name”:”first-id.fr”,”value”:”650349c9714c95f857f63dbd089683c3”}" data-ob-mark="true" data-browser="chrome" data-os="macintel" data-dynload="" data-idx="0" id="outbrain_widget_0" style="">
The value of data-ob-ppid > value should be replaced by the value of the firstid cookie, if present on the page.
Copyright First-id 2023 - all rights reserved
