| title | Normalization and encoding |
|---|---|
| description | 情報を正規化およびエンコードして、安全にデコードできるようにする方法。 |
| hide_table_of_contents | false |
| sidebar_position | 13 |
| displayed_sidebar | docs |
import Link from '@docusaurus/Link';
このページでは、DII の正規化とエンコードに関する情報を提供します。UID2 を使用する際には、正規化とエンコードが正しく行われることが重要です。
メールアドレスなどのユーザー情報を取得し、UID2 の raw UID2 や Advertising Token を作成するには、必要なすべての手順に従うことが非常に重要です。メールアドレスを正規化するかどうか、メールアドレスや電話番号をハッシュ化するかどうかに関係なく、手順を正確に実行してください。そうすることで、作成した UID2 値が同じユーザーによる他のオンライン行動のインスタンスと安全かつ匿名で照合できることを保証できます。
:::important
- raw UID2 と関連する UID2 Token は、ケースセンシティブです。UID2 を使用する場合は、すべての ID とトークンをケースを変更せずに渡すことが重要です。ID が一致しないと、ID の解析やトークンの復号化エラーが発生する可能性があります。
- 必須のステップを一つでも省略した場合（例えば、正規化せずにハッシュ化した場合）、入力データに対して正しい UID2 値は生成されません。
たとえば、データ提供者がJANESaoirse@gmail.comというメールアドレスから UID2 を生成したいとします。このメールアドレスは、正規化されるとjanesaoirse@gmail.comとなり、ハッシュ化されて Base64 でエンコードされた値はku4mBX7Z3qJTXWyLFB1INzkyR2WZGW4ANSJUiW21iI8=となります。
一方で、同じメールアドレスを持つパブリッシャーが、誤って正規化をせずに処理したとします。正規化されていないメールアドレスJANESaoirse@gmail.comをそのままハッシュ化して Base64 でエンコードすると、VpLXEp5N1bj/V1WzjgZsC+FfuYdntAOywSVIO00FD/E=という値になります。この 2 つの異なる値からは、それぞれ異なる UID2 が生成されてしまいます。正しく処理された最初の UID2 は、同じ元のデータから生成された他の UID2 と一致しますが、誤って処理された 2 番目の UID2 は一致しません。
この場合、UID2 が同じユーザーの他のインスタンスと一致しないため、パブリッシャーはターゲティング広告の恩恵を受ける機会を逃してしまいます。 :::
UID2 は、次の種類の Directly Identifying Information (DII) をサポートしています。
- メールアドレス
- 電話番号
UID2 Operator Service にメールアドレスをハッシュ化せずに送信すると、サービスはメールアドレスを正規化してからハッシュ化します。メールアドレスを送信する前に自分でハッシュ化したい場合は、ハッシュ化する前にメールアドレスを正規化する必要があります。
:::important ハッシュ化する前に正規化することで、生成される UID2 値が常に同じになるため、データを照合できるようになります。ハッシュ化の前に正規化しないと、異なる UID2 が生成され、ターゲティング広告の効果が低下する可能性があります。 :::
メールアドレスを正規化するには、次の手順を実行します:
-
メールアドレスの先頭と末尾のスペースを削除します。
-
メールアドレスに大文字が含まれている場合は、小文字に変換します。
-
gmail.comアドレスの場合のみ:- ピリオド (
.)（ASCII decimal code 46/UTF-8 hexadecimal code 2E）がアドレスに含まれている場合、それを削除します。
たとえば、
jane.doe@gmail.comをjanedoe@gmail.comに正規化します。@gmail.comの前にプラス記号 (+) とその後の文字列がある場合、プラス記号 (+)（ASCII decimal code 43/UTF-8 hexadecimal code 2B）とその後のすべての文字を削除します。
たとえば、
janedoe+home@gmail.comをjanedoe@gmail.comに正規化します。 - ピリオド (
:::warning 正規化されたメールアドレスが UTF-8 であることを確認してください。他のエンコーディングシステム（例: UTF-16）ではありません。 :::
様々なシナリオの例は、Normalization examples for email を参照してください。
メールアドレスのハッシュは、正規化されたメールアドレスの Base64 エンコードされた SHA-256 ハッシュです。メールアドレスは最初に正規化され、次に SHA-256 ハッシュアルゴリズムを使用してハッシュ化され、最後にハッシュ値のバイトを Base64 エンコードします。Base64 エンコードは、ハッシュ値のバイトに適用され、16進数でエンコードされた文字列表現ではないことに注意してください。
以下の表は、シンプルな入力メールアドレスと、各手順を適用して安全で不透明な値に到達する結果を示しています。
最終的な値、すなわち SHA-256 ハッシュの 16 進数から Base64 エンコードされた表現が、UID2 Operator endpoint に提供する値となります。
:::warning Base64 エンコーディングを適用する際は、ハッシュの生のバイト列を Base64 エンコードするか、16 進数エンコードされた値を入力として受け取る Base64 エンコーダーを使用してください。テキストを入力として受け取る関数を使用すると、結果として得られる文字列が長くなり、UID2 の目的では無効となります。 :::
| Type | Example | Comments and Usage |
|---|---|---|
| 元のメールアドレス | USER@example.com |
N/A |
| 正規化されたメールアドレス | user@example.com |
正規化は常に最初のステップです。 |
| 正規化されたメールアドレスの SHA-256 ハッシュ | b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514 |
これは、32 バイトの SHA-256 の16進数エンコードされた表現です。 |
| SHA-256 ハッシュの16進数から Base64 へのエンコード | tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ= |
この 44 文字の文字列は、32 バイトの SHA-256 の Base64 エンコードされた表現です。 SHA-256 ハッシュの文字列は、ハッシュ値の 16 進数エンコードされた表現であることに注意してください。ハッシュの生のバイトを Base64 エンコードするか、16 進数エンコードされた値を入力として受け取る Base64 エンコーダーを使用する必要があります。 このエンコードをリクエストボディで送信される email_hash 値に使用します。 |
その他の例は、Normalization examples for email を参照してください。
以下の表は、元のメールアドレスと正規化された値およびハッシュ値の例を示しています。
いくつかの例では、プラス記号（+）を含むメールアドレスと異なるドメインが示されています。gmail アドレスの場合、プラス記号とその後の文字は、@ 記号まで無視されます。他のドメインでは、これらの文字は正規化された値に含まれます。
:::important 自身の UID2 を扱う際には、常に最終値（Base64 エンコードされた値）を UID2 Operator endpoint に提供してください。 :::
| Original Value | Processing Steps and Resulting Values |
|---|---|
| `MyEmail@example.com` `MYEMAIL@example.com` |
1. Normalize: `myemail@example.com` 2. Hash: `16c18d336f0b250f0e2d907452ceb9658a74ecdae8bc94864c23122a72cc27a5` 3. Base64-Encode: `FsGNM28LJQ8OLZB0Us65ZYp07NrovJSGTCMSKnLMJ6U=` |
| `My.Email@example.com` | 1. Normalize: `my.email@example.com` 2. Hash: `e22b53bc6f871274f3a62ab37a3caed7214fc14d676215a96a242fcfada1c81f` 3. Base64-Encode: `4itTvG+HEnTzpiqzejyu1yFPwU1nYhWpaiQvz62hyB8=` |
| `JANESAOIRSE@example.com` `JaneSaoirse@example.com` |
1. Normalize: `janesaoirse@example.com` 2. Hash: `d6670e7a92007f1b5ff785f1fc81e53aa6d3d7bd06bdf5c473cdc7286c284b6d` 3. Base64-Encode: `1mcOepIAfxtf94Xx/IHlOqbT170GvfXEc83HKGwoS20=` |
| `jane.saoirse@example.com` `Jane.Saoirse@example.com` |
1. Normalize: `jane.saoirse@example.com` 2. Hash: `b196432c7b989a2ca91c83799957c515da53e6c13abf20b78fea94f117e90bf8` 3. Base64-Encode: `sZZDLHuYmiypHIN5mVfFFdpT5sE6vyC3j+qU8RfpC/g=` |
| `JaneSaoirse+Work@example.com` | 1. Normalize: `janesaoirse+work@example.com` 2. Hash: `28aaee4815230cd3b4ebd88c515226550666e91ac019929e3adac3f66c288180` 3. Base64-Encode: `KKruSBUjDNO069iMUVImVQZm6RrAGZKeOtrD9mwogYA=` |
| `JANE.SAOIRSE@gmail.com` `Jane.Saoirse@gmail.com` `JaneSaoirse+Work@gmail.com` |
1. Normalize: `janesaoirse@gmail.com` 2. Hash: `92ee26057ed9dea2535d6c8b141d48373932476599196e00352254896db5888f` 3. Base64-Encode: `ku4mBX7Z3qJTXWyLFB1INzkyR2WZGW4ANSJUiW21iI8=` |
:::important UID2 Operator Service へのリクエストで電話番号を送信する前に、必ず電話番号を正規化してください。ハッシュ化とエンコードを適用するかどうかに関係なく、正規化が必要です。 :::
ここでは、電話番号の正規化ルールについて知っておくべきことを説明します:
- UID2 Operator は、国際的な電話番号形式である E.164 形式の電話番号を受け入れます。これにより、グローバルな一意性が確保されます。
- E.164 電話番号は、最大 15 桁の数字を含むことができます。
- 正規化された E.164 電話番号は、スペース、ハイフン、括弧、その他の特殊文字を含まない次の構文を使用します:
[+] [国コード] [加入者番号（市外局番を含む）]例:- US:
1 (234) 567-8901は+12345678901に正規化されます。 - Singapore:
65 1243 5678は+6512345678に正規化されます。 - Australia: 携帯電話番号
0491 570 006は、国番号を追加し、先頭のゼロを削除して正規化されます：+61491570006。
- US:
:::warning 正規化された電話番号が UTF-8 であることを確認してください。他のエンコーディングシステム（例: UTF-16）ではありません。 :::
電話番号のハッシュは、正規化された電話番号の Base64 エンコードされた SHA-256 ハッシュです。電話番号は最初に正規化し、次に SHA-256 ハッシュアルゴリズムを使用してハッシュ化し、最後にハッシュ値のバイトを Base64 エンコードします。Base64 エンコードは、ハッシュ値のバイトに適用され、16進数でエンコードされた文字列表現ではないことに注意してください。
以下の表は、単純な入力電話番号の例と、各ステップを適用して安全で不透明な URL-safe な値にする結果を示しています。
最終値、すなわち SHA-256 ハッシュの 16進数から Base64 エンコードされた表現は、UID2 Operator endpoint に提供する値となります。
:::warning Base64 エンコーディングを適用する際は、ハッシュの生のバイト列を Base64 エンコードするか、16進数エンコードされた値を入力として受け取る Base64 エンコーダーを使用してください。テキストを入力として受け取る関数を使用すると、結果として得られる文字列が長くなり、UID2 の目的では無効となります。 :::
| Type | Example | Comments and Usage |
|---|---|---|
| 元の電話番号 | 1 (234) 567-8901 |
N/A |
| 正規化された電話番号 | +12345678901 |
正規化は常に最初のステップです。 |
| 正規化された電話番号の SHA-256 ハッシュ | 10e6f0b47054a83359477dcb35231db6de5c69fb1816e1a6b98e192de9e5b9ee |
この 64 文字の文字列は、32 バイト SHA-256 の16進数エンコードされた表現です。 |
| SHA-256 ハッシュの 16進数から Base64 へのエンコード | EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4= |
この 44 文字の文字列は、32 バイト SHA-256 の Base64 エンコードされた表現です。 注: SHA-256 ハッシュは16進数の値です。16進数の値を入力として受け取る Base64 エンコーダーを使用する必要があります。このエンコードは、リクエストボディに送信される phone_hash 値に使用します。 |
メールアドレスや電話番号のハッシュを生成する方法の例は、Example code: Hashing and Base64 encoding を参照してください。
正規化、ハッシュ化、エンコードが正しく行われているかを確認するには、UID2 hashing tool を使用できます。
:::note
UID2 ハッシュツールは、以前の場所 https://unifiedid.com/examples/hashing-tool/ から移動しました。ハッシュツールへの保存済みリンクがある場合は、必ず最新の URL に更新してください。
:::
Email または Phone Number を選択し、値を入力または貼り付けてから Enter をクリックします。
このツールは、次のことを行います:
-
Email: 以下の 3 つの値を表示します:
- Normalized value
- Hashed value
- Base64-encoded value
-
Phone: 以下の 2 つの値を表示します:
- Hashed value
- Base64-encoded value
:::important 電話番号の場合、最初にデータを正規化する必要があります。 :::
入力したデータが有効なメールアドレスまたは電話番号の形式でない場合、または電話番号が正規化されていない場合、ツールはエラーを返します。
このツールを使用して、内部プロセスが UID2 の正規化、ハッシュ化、およびエンコードされた値を正しく作成するように設定されていることを確認できます。
:::note このセクションはパブリッシャー向けです。パブリッシャーは、直接識別可能な情報 (DII) を使用して UID2 token を生成する唯一の参加者です。 :::
エンドツーエンドで完全なトークン生成パイプラインを検証し、正規化、ハッシュ化、およびエンコードされた値から生成された UID2 Token が正しいことを確認するには、UID2 Token Validator を使用してください。
いずれの場合も、自身で DII を処理準備するための手順を実行し、その後 UID2 hashing tool を使用して結果値を確認してください。結果が一致しない場合は、各手順を確認してエラー箇所を特定してください。
問題が発生したりエラーが出たりする場合、あるいは手順を正しく実行できているか確認したい場合にも、以下の点をチェックしてみてください。
-
Phone numbers: 最初のステップとして、正規化を確実に行うこと—正しく正規化すること—が重要です。
このサービスはメールアドレスを正規化しますが、電話番号の正規化はできません。例えば、国コードが欠落している場合の値を判断できません。以下のリソースを利用してください。
- 正規化手順: Phone number normalization.
- 照合ツール: UID2 hashing tool.
-
Use the Base64-encoded value: このプロセスには、ハッシュ値のバイト列を正規化、ハッシュ化、Base64 エンコードする手順が含まれます。UID2 を生成する際の入力は、この Base64 エンコードされた値です。必ずこの 44 文字の文字列値を使用してください。
-
以下のエラーメッセージが表示される場合があります：「The hashing value must be 44 characters. (ハッシュ値は44文字でなければなりません）」。この場合、使用しているハッシュ関数に問題があります。SHA-256 ハッシュの 16 進数から Base64 へのエンコードを使用してください。詳細はEmail address hash encodingまたはPhone number hash encodingを参照してください。確認のため、UID2 hashing tool でテストしてください。