Merge pull request #683 from IABTechLab/aaq-3842-python-sdk-identity-…

…buckets

Add Python sdk guide for monitoring salt bucket rotations

docs/sdks/sdk-ref-python.md

@@ -20,9 +20,9 @@ You can use the SDK for Python on the server side to facilitate the following:
 
 This SDK simplifies integration with UID2 for any DSPs or UID2 sharers who are using Python for their server-side coding. The following table shows the functions it supports.
 
-| Encrypt Raw UID2 to UID2 Token | Decrypt UID2 Token to Raw UID2 | Generate UID2 Token from DII | Refresh UID2 Token | Map DII to Raw UID2s       |
-| :--- | :--- | :--- | :--- | :--- |
-| ✅ | ✅ | ✅ | ✅ | ✅ |
+| Encrypt Raw UID2 to UID2 Token | Decrypt UID2 Token to Raw UID2 | Generate UID2 Token from DII | Refresh UID2 Token | Map DII to Raw UID2s | Monitor Rotated Salt Buckets      |
+| :--- | :--- | :--- | :--- | :--- |:--- |
+| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 ## API Permissions
 
@@ -209,6 +209,12 @@ If you're using server-side integration (see [Publisher Integration Guide, Serve
    If the user has opted out, this method returns `None`, indicating that the user's identity should be removed from the session. To confirm optout, you can use the `token_refresh_response.is_optout()` function.
 
 ## Usage for Advertisers/Data Providers
+There are two operations that apply to Advertisers/Data Providers:
+- [Map DII to raw UID2s](#map-dii-to-raw-uid2s)
+- [Monitor rotated salt buckets](#monitor-rotated-salt-buckets)
+
+### Map DII to Raw UID2s
+To map email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs, follow these steps:
 1. Create an instance of `IdentityMapClient` as an instance variable.
    ```py
    client = IdentityMapClient(base_url, api_key, client_secret)
@@ -219,7 +225,9 @@ If you're using server-side integration (see [Publisher Integration Guide, Serve
    identity_map_response = client.generate_identity_map(IdentityMapInput.from_emails(["[email protected]", "[email protected]"]))
    ```
 
->Note: The SDK hashes input values before sending them. This ensures that raw email addresses and phone numbers do not leave your server.
+   :::note
+   The SDK hashes input values before sending them. This ensures that raw email addresses and phone numbers do not leave your server.
+   :::
 
 3. Retrieve the mapped and unmapped results as follows:
    ```py
@@ -236,7 +244,31 @@ If you're using server-side integration (see [Publisher Integration Guide, Serve
         unmapped_identity = unmapped_identities.get("[email protected]")
         reason = unmapped_identity.get_reason()
    ```
+### Monitor Rotated Salt Buckets
+To monitor salt buckets, follow these steps:
+1. Create an instance of `IdentityMapClient` as an instance variable or reuse the one from [Map DII to raw UID2s:](#map-dii-to-raw-uid2s)
+   ```py
+   client = IdentityMapClient(base_url, api_key, client_secret)
+   ```
+2. Call a function that takes the timestamp string as input and generates an `IdentityBucketsResponse` object. The timestamp string should be in ISO 8601 format: `YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]]`.
+The following examples are valid timestamp strings:
+   - Date in local timezone: `2024-08-18`
+   - Date and time in UTC: `2024-08-18T14:30:15.123456+00:00`
+   - Date and time in EST: `2024-08-18T14:30:15.123456-05:00`
 
+   ```py
+      since_timestamp = '2024-08-18T14:30:15+00:00'
+      identity_buckets_response = client.get_identity_buckets(datetime.fromisoformat(since_timestamp))
+   ```
+3. The `IdentityBucketsResponse` object contains the `bucket_id` and the `last_updated` timestamp which is in UTC. Iterate through the list of rotated salt buckets and extract the `bucket_id` and `last_updated` timestamp as follows:
+   ```py
+   if identity_buckets_response.buckets:
+       for bucket in identity_buckets_response.buckets:
+           bucket_id = bucket.get_bucket_id()         # example "bucket_id": "a30od4mNRd"
+           last_updated = bucket.get_last_updated()   # example "last_updated" "2024-08-19T22:52:03.109"
+   else:
+       print("No bucket was returned")
+   ```
 ## Usage for DSPs
 
 The following instructions provide an example of how you can decode <Link href="../ref-info/glossary-uid#gl-bidstream">bidstream</Link> tokens using the SDK for Python as a DSP.