Merged main

Author: gmsdelmundo

docs/endpoints/post-identity-map-v2.md

@@ -20,7 +20,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User
 This documentation is for version 2 of this endpoint, which is not the latest version. For the latest version, v3, see [POST /identity/map](post-identity-map.md).
 
 :::note
-If you're using the previous version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from v2 Identity Map](post-identity-map.md#migration-from-v2-identity-map).
+If you're using the previous version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from v2 Identity Map](post-identity-map.md#migration-from-v2-identity-map). For deprecation information, see [Deprecation Schedule: Endpoint Versions](../ref-info/deprecation-schedule.md#endpoint-versions).
 :::
 
 ## Batch Size and Request Parallelization Requirements

docs/endpoints/post-identity-map.md

@@ -7,6 +7,7 @@ displayed_sidebar: docs
 ---
 
 import Link from '@docusaurus/Link';
+import POSTIdentityMapImprovements from '../snippets/_post-identity-map-improvements-v3.mdx';
 
 # POST /identity/map
 
@@ -206,13 +207,7 @@ The following sections provide general information and guidance for migrating to
 
 ### Version 3 Improvements
 
-The v3 Identity Map API provides the following improvements over v2:
-
-- **Simplified Refresh Management**: You can monitor for UID2s reaching `refresh_from` timestamps instead of polling <Link href="../ref-info/glossary-uid#gl-salt-bucket-id">salt buckets</Link> for rotation.
-- **Previous UID2 Access**: You have access to previous raw UID2s for 90 days after rotation for campaign measurement.
-- **Single Endpoint**: You use only one endpoint, `/v3/identity/map`, instead of both `/v2/identity/map` and `/v2/identity/buckets`.
-- **Multiple Identity Types in One Request**: You can process both emails and phone numbers in a single request.
-- **Improved Performance**: The updated version uses significantly less bandwidth to process the same amount of DII.
+<POSTIdentityMapImprovements />
 
 ### Key Differences Between v2 and v3
 

docs/getting-started/gs-faqs.md

@@ -175,7 +175,7 @@ Here are some frequently asked questions for advertisers and data providers usin
 - [Does the same DII always result in the same raw UID2?](#does-the-same-dii-always-result-in-the-same-raw-uid2)
 - [If two operators process the same DII, are the results the same?](#if-two-operators-process-the-same-dii-are-the-results-the-same)
 - [How do I know when to refresh the UID2 due to salt bucket rotation?](#how-do-i-know-when-to-refresh-the-uid2-due-to-salt-bucket-rotation)
-- [Do refreshed emails get assigned to the same bucket with which they were previously associated?](#do-refreshed-emails-get-assigned-to-the-same-bucket-with-which-they-were-previously-associated)
+- [Do refreshed emails get assigned to the same bucket that they were previously associated with?](#do-refreshed-emails-get-assigned-to-the-same-bucket-that-they-were-previously-associated-with)
 
 #### How do I know when to refresh a raw UID2?
 
@@ -198,7 +198,7 @@ A raw UID2 for a specific user changes roughly once per year. The latest version
 
 For implementations that reference earlier versions of this endpoint (see [POST /identity/map v2](../endpoints/post-identity-map-v2.md)):
 
-Even though each <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt bucket</Link> is updated roughly once a year, individual bucket updates are spread over the year. This means that about 1/365th of all buckets are rotated daily. If fidelity is critical, consider calling the [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md) endpoint more frequently; for example, hourly.
+Even though each <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt bucket</Link> is updated roughly once a year, individual bucket updates are spread over the year. This means that about 1/365th of all buckets are rotated daily. If fidelity is critical, consider calling the [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md) endpoint more frequently: for example, hourly.
 
 #### How should I generate the SHA-256 of DII for mapping?
 
@@ -224,7 +224,7 @@ If a user opts out through your website, you should follow your internal procedu
 
 In general yes, the process of generating a raw UID2 from DII is the same, and results in the same value, no matter who sent the request. If two UID2 participants were to send the same email address to the [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) endpoint at the same time, they would both get the same raw UID2 in response.
 
-However, there is a variable factor that's used in generating the raw UID2. The underlying values are refreshed roughly once per year (for details, see [How often should raw UID2s be refreshed for incremental updates?](#how-often-should-raw-uid2s-be-refreshed-for-incremental-updates)). If these values change between one request and another, those two requests result in two different raw UID2, even when the DII is the same.
+However, there is a variable factor that's used in generating the raw UID2. The underlying values are refreshed roughly once per year (for details, see [How often should raw UID2s be refreshed for incremental updates?](#how-often-should-raw-uid2s-be-refreshed-for-incremental-updates)). If these values change between one request and another, those two requests result in two different raw UID2s, even when the DII is the same.
 
 For more information, see [Monitor for Raw UID2 Refresh](../guides/integration-advertiser-dataprovider-overview.md#5-monitor-for-raw-uid2-refresh) in the *Advertiser/Data Provider Integration Guide*.
 
@@ -240,13 +240,13 @@ However, if a publisher sends DII in a request for a <Link href="../ref-info/glo
 
 #### How do I know when to refresh the UID2 due to salt bucket rotation?
 
-Metadata supplied with the UID2 generation request indicates the <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt bucket</Link> used for generating the UID2. Salt buckets persist and correspond to the underlying <Link href="../ref-info/glossary-uid#gl-dii">DII</Link> used to generate a UID2. Use the [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md) endpoint to return which salt buckets rotated since a given timestamp. The returned rotated salt buckets inform you which UID2s to refresh.
+Metadata supplied with the UID2 generation request indicates the <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt bucket</Link> used for generating the UID2. Salt buckets persist and correspond to the underlying <Link href="../ref-info/glossary-uid#gl-dii">DII</Link> used to generate a raw UID2. Use the [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md) endpoint to return which salt buckets rotated since a given timestamp. The returned rotated salt buckets inform you which UID2s to refresh.
 
 :::note
 We do not make any promises about when the rotation takes place. To stay as up-to-date as possible, we recommend doing the checks once per hour.
 :::
 
-#### Do refreshed emails get assigned to the same bucket with which they were previously associated?
+#### Do refreshed emails get assigned to the same bucket that they were previously associated with?
 
 Not necessarily. After you remap emails associated with a particular bucket ID, the emails might be assigned to a different bucket ID. To check the bucket ID, see [Generate Raw UID2s from DII](../guides/integration-advertiser-dataprovider-overview.md#1-generate-raw-uid2s-from-dii) and save the returned raw UID2 and bucket ID again.
 
@@ -262,6 +262,7 @@ Here are some frequently asked questions for demand-side platforms (DSPs).
 - [Where do I get the decryption keys?](#where-do-i-get-the-decryption-keys)
 - [How many decryption keys may be present in memory at any point?](#how-many-decryption-keys-may-be-present-in-memory-at-any-point)
 - [How do I know when to refresh mapped raw UID2s?](#how-do-i-know-when-to-refresh-mapped-raw-uid2s)
+- [How do I know if/when the raw UID2 has rotated?](#how-do-i-know-ifwhen-the-raw-uid2-has-rotated)
 - [Should the DSP be concerned with latency?](#should-the-dsp-be-concerned-with-latency)
 - [How should the DSP maintain proper frequency capping with UID2?](#how-should-the-dsp-maintain-proper-frequency-capping-with-uid2)
 - [Will all user opt-out traffic be sent to the DSP?](#will-all-user-opt-out-traffic-be-sent-to-the-dsp)
@@ -288,7 +289,7 @@ There may be thousands of decryption keys present in the system at any given poi
 
 #### How do I know when to refresh mapped raw UID2s?
 
-See [Advertisers and Data Providers section](#how-do-i-know-when-to-refresh-a-raw-uid2).
+See [How do I know when to refresh a raw UID2?](#how-do-i-know-when-to-refresh-a-raw-uid2) in the FAQs for Advertisers and Data Providers.
 
 #### How do I know if/when the raw UID2 has rotated?
 
@@ -300,7 +301,7 @@ The UID2 service does not introduce latency into the bidding process. Any latenc
 
 #### How should the DSP maintain proper frequency capping with UID2?
 
-The UID2 has the same chance as a cookie of becoming stale. Hence, the DSP can adapt the same infrastructure currently used for cookie or deviceID-based frequency capping for UID2. For details, see [How do I know when to refresh a raw UID2?](#how-do-i-know-when-to-refresh-a-raw-uid2).
+The UID2 has the same chance as a cookie of becoming stale. Hence, the DSP can adapt the same infrastructure currently used for cookie or deviceID-based frequency capping for UID2. For details, see [How do I know when to refresh a raw UID2?](#how-do-i-know-when-to-refresh-a-raw-uid2)
 
 #### Will all user opt-out traffic be sent to the DSP?
 

docs/getting-started/gs-permissions.md

@@ -18,13 +18,13 @@ For each UID2 participant that has API Key and Client Secret, the permissions ar
 If you're a publisher and are implementing UID2 on the client side, API permissions do not apply to you. Instead, you'll receive a different set of credentials that are specifically for generating a client-side token request. For details, see [Subscription ID and Public Key](gs-credentials.md#subscription-id-and-public-key).
 :::
 
-A participant can have one or several sets of API credentials with associated permissions. In cases where you have m ore than one API permission, you have the option to have a separate set of credentials for each permission or have a single set of credentials for all permissions. We recommend having a separate set of credentials for each permission. 
+A participant can have one or several sets of API credentials with associated permissions. In cases where you have more than one API permission, you have the option to have a separate set of credentials for each permission or have a single set of credentials for all permissions. We recommend having a separate set of credentials for each permission. 
 
 The following table lists the key permissions, the types of participants that commonly use them, and a summary of the key associated activities.
 
 | Name | Participant Type | Permissions |
 | :--- | :--- | :--- |
-| Generator | Publishers | Permission to call the [POST&nbsp;/token/generate](../endpoints/post-token-generate.md), [POST&nbsp;/token/validate](../endpoints/post-token-validate.md), and [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md) endpoints, to generate UID2 tokens from <Link href="../ref-info/glossary-uid#gl-dii">DII</Link> and to refresh them, using one of these integration methods:<ul><li>A Prebid integration</li><li>The SDK for JavaScript</li><li>An integration that directly calls the applicable API endpoints for retrieving and managing UID2 tokens.</li></ul> |
+| Generator | Publishers | Permission to call the [POST&nbsp;/token/generate](../endpoints/post-token-generate.md), [POST&nbsp;/token/validate](../endpoints/post-token-validate.md), and [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md) endpoints, to generate UID2 tokens from <Link href="../ref-info/glossary-uid#gl-dii">DII</Link> and to refresh them, using one of these integration methods:<ul><li>A Prebid integration</li><li>The SDK for JavaScript</li><li>An integration that directly calls the applicable API endpoints for retrieving and managing UID2 tokens</li></ul> |
 | Bidder | DSPs | Permission to decrypt UID2 tokens coming in from the <Link href="../ref-info/glossary-uid#gl-bidstream">bidstream</Link> from publishers into raw UID2s for bidding purposes. |
-| Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:<ul><li>Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake</li><li>Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s.</li></ul> |
-| Mapper | Advertisers<br/>Data Providers | Permission to call the following endpoints to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s, and refresh timestamps:<ul><li>[POST&nbsp;/identity/map](../endpoints/post-identity-map.md) (latest version)</li><li>The earlier v2 identity mapping endpoints: [POST&nbsp;/identity/map (v2)](../endpoints/post-identity-map.md) and [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md).</li></ul> |
+| Sharer | Any participant type that takes part in UID2 sharing.<br/>For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:<ul><li>Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake</li><li>Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s</li></ul> |
+| Mapper | Advertisers<br/>Data Providers | Permission to call the following endpoints to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s, and refresh timestamps:<ul><li>[POST&nbsp;/identity/map](../endpoints/post-identity-map.md) (latest version)</li><li>The earlier v2 identity mapping endpoints: [POST&nbsp;/identity/map (v2)](../endpoints/post-identity-map.md) and [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md)</li></ul> |

docs/guides/integration-advertiser-dataprovider-endpoints.md

@@ -95,7 +95,7 @@ You could also send conversion information via API or pixels for measurement (at
 
 A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes roughly once per year as part of the UID2 refresh process.
 
-The v3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data, it is guaranteed that it won't refresh before that time.
+The v3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data. It is guaranteed that it won't refresh before that time.
 
 We recommend checking for refresh opportunities daily. The following table shows the steps for monitoring raw UID2 refresh.
 

docs/guides/operator-guide-aks-enclave.md

@@ -276,7 +276,7 @@ az aks create \
     --resource-group ${RESOURCE_GROUP} \
     --name ${AKS_CLUSTER_NAME} \
     --location ${LOCATION} \
-    --kubernetes-version 1.29.13 \
+    --kubernetes-version 1.33 \
     --network-plugin azure \
     --network-policy calico \
     --vnet-subnet-id ${AKS_SUBNET_ID} \
@@ -292,6 +292,9 @@ az aks create \
     --nodepool-name oprnodepool \
     --os-sku Ubuntu
 ```
+:::note
+Be sure to use the latest supported Kubernetes version, using the `--kubernetes-version` flag. If you use an earlier version, you must enable Long-Term Support (LTS). For details, see [Long-term support for Azure Kubernetes Service (AKS) versions](https://learn.microsoft.com/en-us/azure/aks/long-term-support) in the Microsoft documentation.
+:::
 
 #### Get the Principal ID of the Managed Identity
 
@@ -376,23 +379,43 @@ After completing the previous steps, follow these steps to update placeholder va
 1. Get the managed identity ID by running the following:
 
    ```
-   MANAGED_IDENTITY_ID=$("az identity show --name "${MANAGED_IDENTITY}" --resource-group "${RESOURCE_GROUP}" --query id --output tsv")
+   MANAGED_IDENTITY_ID=$(az identity show --name "${MANAGED_IDENTITY}" --resource-group "${RESOURCE_GROUP}" --query id --output tsv)
    ```
 
 2. In the `operator.yaml` file, update `microsoft.containerinstance.virtualnode.identity` with the managed identity ID that was returned:
 
+   - For Linux, run:
+
    ```
    sed -i "s#IDENTITY_PLACEHOLDER#$MANAGED_IDENTITY_ID#g" "operator.yaml"
    ```
 
+   - For MacOS, run:
+
+   ```
+   sed -i '' "s#IDENTITY_PLACEHOLDER#$MANAGED_IDENTITY_ID#g" "operator.yaml"
+   ```
+
 3. Update the Vault Key and Secret names with the environment variables:
 
+   - For Linux, run:
+
+
    ```
    sed -i "s#VAULT_NAME_PLACEHOLDER#$KEYVAULT_NAME#g" "operator.yaml"
    sed -i "s#OPERATOR_KEY_SECRET_NAME_PLACEHOLDER#$KEYVAULT_SECRET_NAME#g" "operator.yaml"
    sed -i "s#DEPLOYMENT_ENVIRONMENT_PLACEHOLDER#$DEPLOYMENT_ENV#g" "operator.yaml"
    ```
 
+   - For MacOS, run:
+
+   ```
+   sed -i '' "s#VAULT_NAME_PLACEHOLDER#$KEYVAULT_NAME#g" "operator.yaml"
+   sed -i '' "s#OPERATOR_KEY_SECRET_NAME_PLACEHOLDER#$KEYVAULT_SECRET_NAME#g" "operator.yaml"
+   sed -i '' "s#DEPLOYMENT_ENVIRONMENT_PLACEHOLDER#$DEPLOYMENT_ENV#g" "operator.yaml"
+   ```
+
+
 #### Deploy Operator
 
 Follow these steps to deploy the Private Operator:

docs/ref-info/deprecation-schedule.md

@@ -79,3 +79,16 @@ The latest ZIP file is linked in the Release Notes column in the following table
 | ------- | ------ | ------ | ------ | ------ |
 | Q2 2025 | xxx | xxx | xxx | xxx | -->
 <!-- | Q1 2025 | 5.49.7 | [v5.49.7](https://github.com/IABTechLab/uid2-operator/releases/tag/v5.49.7) | Mar 19, 2025 | Mar 31, 2026 | -->
+
+## Endpoint Versions
+
+Version 2 of the `POST /identity/map` endpoint has been superseded by version 3, which includes the additional advantages listed in [Version 3 Improvements](../endpoints/post-identity-map.md#version-3-improvements).
+
+With version 3 of the `POST /identity/map endpoint`, the `POST /identity/buckets` endpoint is no longer used at all.
+
+The following table shows the deprecation schedule for the v2 endpoints.
+
+Endpoint | Deprecation Date | 
+| ------- | ------ |
+| `POST /v2/identity/map` | June 30, 2026 |
+| `POST /v2/identity/buckets` | June 30, 2026 |

docs/ref-info/updates-doc.md

@@ -38,7 +38,7 @@ We've released a new version of the Identity Map API (v3) that provides signific
 
 ## Q1 2025
 
-The following documents were released in this quarter.
+The following documents were released in the first quarter of 2025.
 
 <CustomTagsContainer tags="Guides, Private Operator">
 

docs/sdks/sdk-ref-cplusplus.md

@@ -165,7 +165,3 @@ The following instructions provide an example of how you can implement sharing u
          // check decrypted.GetStatus() for the failure reason 
       }
       ```
-
-## FAQs
-
-For a list of frequently asked questions for DSPs, see [FAQs for DSPs](../getting-started/gs-faqs.md#faqs-for-dsps).

docs/sdks/sdk-ref-csharp-dotnet.md

@@ -137,9 +137,9 @@ client.Refresh();
 ```
 
 3. Decrypt a token into a raw UID2. Pass the token, and then do one of the following: 
- * If the bid request originated from a publisher's website, pass the domain name. The domain name must be all lower case, without spaces and without subdomain. For example, for `Subdomain.DOMAIN.com`, pass `domain.com` instead.
- * If the bid request originated from a mobile app, pass the <Link href="../ref-info/glossary-uid#gl-app-name">app name</Link>.
- * Otherwise, pass `null`.
+   * If the bid request originated from a publisher's website, pass the domain name. The domain name must be all lower case, without spaces and without subdomain. For example, for `Subdomain.DOMAIN.com`, pass `domain.com` instead.
+   * If the bid request originated from a mobile app, pass the <Link href="../ref-info/glossary-uid#gl-app-name">app name</Link>.
+   * Otherwise, pass `null`.
 
 
 ```cs
@@ -211,7 +211,3 @@ else
 ```
 
 For a full example, see the `ExampleSharingClient` method in [SampleApp/Program.cs](https://github.com/IABTechLab/uid2-client-net/blob/main/src/SampleApp/Program.cs).
-
-## FAQs
-
-For a list of frequently asked questions for DSPs, see [FAQs for DSPs](../getting-started/gs-faqs.md#faqs-for-dsps).