sch-UID2-5558 v3 identity map #887
Conversation
docs/endpoints/post-identity-map.md
Outdated
|
|
||
| Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). | ||
|
|
||
| For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). | ||
|
|
||
| ## Version | ||
|
|
||
| This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. No specific migration steps are needed. |
There was a problem hiding this comment.
The endpoints are not exactly the same - some migration steps would be necessary then?
There was a problem hiding this comment.
Ah yes we'll have migration steps. I'll put this as TODO until we've written those up
docs/endpoints/post-identity-map.md
Outdated
| @@ -47,57 +53,57 @@ The integration environment and the production environment require different <Li | |||
| ### Unencrypted JSON Body Parameters | |||
|
|
|||
| :::important | |||
| You must include only **one** of the following four conditional parameters as a key-value pair in the JSON body of the request when encrypting it. | |||
| You can include one or more of the following four parameters as key-value pairs in the JSON body of the request when encrypting it. | |||
There was a problem hiding this comment.
You must? Not including any would be an error?
docs/endpoints/post-identity-map.md
Outdated
| The response body includes the properties shown in the following table. | ||
| | Body Parameter | Data Type | Attribute | Description | | ||
| |:---------------|:----------------------------|:-----------------------|:------------------------------------------------------------------------------------------------| | ||
| | `email` | array of mapped DII objects | Conditionally Required | The list of mapped DII objects corresponding to the list of emails in the request. | |
There was a problem hiding this comment.
What does "Conditionally Required" mean here?
There was a problem hiding this comment.
Ah this isn't meant to be in the response table - good catch
docs/endpoints/post-identity-map.md
Outdated
|
|
||
| | Property | Data Type | Description | | ||
| |:---------|:----------|:------------------------------------------------------------------| | ||
| | `e` | string | The reason for being unable to map the DII to an advertising ID. | |
There was a problem hiding this comment.
Optout is not technically an error - the client did not do anything wrong. It is a special status. Is it worthwhile listing this value for e explicitly as part of the contract?
There was a problem hiding this comment.
Do you mean explicitly listing that the two possible values are "optout" and "invalid identifier" in this table?
| # POST /identity/map (v2) | ||
|
|
||
| :::important | ||
| This documentation is for earlier versions of the `POST /identity/map` endpoint. If you're using an earlier version, we recommend upgrading. No specific migration steps are needed. For the latest version, v3, see [POST /identity/map](post-identity-map.md). |
There was a problem hiding this comment.
should this be "an earlier version" since there is only one version covered here? some migration guide would be helpful here - it is not just switching to new URL: request and response formats have changed
There was a problem hiding this comment.
Good point, updated wording and added a [TODO] for migration
There was a problem hiding this comment.
We have a separate ticket to write a migration guide from V2 to V3, the purpose of this page is to document the v3 identity map API spec
There was a problem hiding this comment.
I think for now we should remove mentions of migration, we can link it when we write the migration guide
| 複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 と <Link href="../ref-info/glossary-uid#gl-salt-bucket-id">salt bucket IDs</Link> にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます | ||
|
|
||
| Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) を参照してください。 | ||
|
|
||
| UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳細は、[User Opt-Out](../getting-started/gs-opt-out.md) を参照してください。 | ||
|
|
||
| ## Version | ||
|
|
||
| This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. For migration steps, see [TODO]. |
There was a problem hiding this comment.
For now I think we should remove "If you're using an earlier version, we recommend that you upgrade your integration. For migration steps, see [TODO]."
There was a problem hiding this comment.
@sophia-chen-ttd @vishalegbert-ttd we should not make any edits that add English copy into the Japanese version. My bad. I see my comment in https://github.com/IABTechLab/uid2docs/pull/886/files#diff-809a0199a403c7ccc7be74f78522559c07b514520b28a7f5b5c3b24a88364f2f. We need to make any necessary changes so that it builds correctly and the links work, but leave the rest for the translator. Apologies for this.
| # POST /identity/map (v2) | ||
|
|
||
| :::important | ||
| This documentation is for an earlier version of the `POST /identity/map` endpoint. If you're using this earlier version, we recommend upgrading. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. |
There was a problem hiding this comment.
For now I think we should remove this whole alert block
There was a problem hiding this comment.
@vishalegbert-ttd I do think that somehow we need to differentiate between the two versions, and who should use which. Usually, for versioning, we do that at the top of the doc: see https://unifiedid.com/docs/sdks/sdk-ref-javascript-v3. That's why this is in here, FYI.
|
|
||
| Identifiers that cannot be mapped to a UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the identifier is considered invalid or if the identifier has opted out from the UID2 ecosystem. In these cases, the response status is still "success". | ||
| The response arrays preserve the order of input arrays. Each element in the response array maps directly to the element at the same index in the corresponding request array. This ensures that results can be reliably associated with their corresponding inputs based on array position. |
There was a problem hiding this comment.
It'd be nice to get an example for this. We have an example input above and an example output below, but they do not actually match and do not illustrate the point.
Preview: https://unifiedid2.github.io/uid2-docs-preview/docs/endpoints/post-identity-map