Code Quickstart
Identities and Identifiers
The ADARA Privacy SDK accepts PII for an individual and transforms it into a privacy-safe set of tokens. Tokens, by themselves, are intentionally useless; they are useful only when maintained as a set of tokens pointing to an individual user. The classes within the this reflect this by using a set of Identifiers that belong to an Identity:
from adara_privacy import Identity, Identifiermy_identity = Identity( # pass the identifier type as an arg (placement doesn't matter) Identifier('email', 'someone.special@somedomain.com'), # or use a named argument Identifier(state_id = "D1234567"), )An identity can have any number of identifiers; one or more tokens will be produced for each identifier you pass (based on your common salt configurations). Each identifier is associated with an identifier type, which can correspond to a specific tokenization algorithm used for that type.
The ADARA Privacy SDK supports the following identifiers out of the box:
| Type Value | Description | Argument Keywords |
|---|---|---|
cookie | Persistent cookie identifier | single: cookie |
customer_id | Internal customer ID | single: customer_id |
drivers_license | State-issued driver's license number | single: drivers_license |
email | Clear text email address | single: email |
hashed_email | Hashed email address | single: hashed_email |
membership_id | Membership / loyalty ID | single: single: membership_id |
passport | Passport number | single: passport |
social_security | Social security number | single: social_security |
state_id | Other state ID | single: state_id |
streetname_zipcode | Street name and zip code | composite: street_name, zip_code |
You may also extend the ADARA Privacy SDK with identifier types of your own. |
Tokens
Each Identifier can be turned into tokens. The tokens are generated using the private salt and one or more common salts defined in your local configuration. Using these salts and some standard hashing algorithms, the ADARA Privacy SDK turns the raw PII from the identifier into a private token and one or more common tokens. The type of identifier (example: email or driver license number) is also returned with the token, as well as an optional label.
You can see the tokens for an Identity by invoking the to_tokens() method:
xxxxxxxxxxprint( json.dumps( my_identity.to_tokens() ))For the first example above, this yields the following output (or something similar, based on your client salt):
xxxxxxxxxx{ "package_token": "1dec707d16232521608c722299d03e6a34f47b20d3bbacb2a0738384c06fd029", "tokens": [ { "private": "15ba6cd3b7f2618e680180706ae65850093ee165d36fb743c4d64ec3a51bd823", "adara": "4447b2c72b9aa03977af4b9f085feaf001587b652f36a914363d8eb709bc20bf", "my_consortium": "b84057a0bf979e28d53b846c2f3148a1f58e07a282f1bd768ce73a0fce347aef", "my_other_consortium": "8077ddc77cf8735dd6143d929f9f04deceec33e53331fe8466ad63934e33be3e", "type": "email" }, { "private": "8edeb62e51ff5e19bba160b2c00c1747578fc5f3ae0c2f10a1bafd1d3522fbf2", "adara": "141dd951d0a54dfb320bdea0f5c35c9b379726780670d3b8cd6dd0d5341bb106", "my_consortium": "b0a85ec62d29b137d403155301cdb613dcf7474d40345b9c141cd8d3b3a32dcd", "my_other_consortium": "923c5edbd61954b09f20044be534b7a14c3ebae717eb0c25eb81679df064d5fd", "type": "state_id" } ]}Package Tokens
The ADARA Privacy SDK returns tokens for each identifier and salt combination. For a given Identity instance, this can result in a large number of individual tokens, which is not necessarily convenient for storing alongside your data. To solve this issue, each tokenization result contains a package token. This is a private token derived from all the identifiers within an identity.
The package token is at least as good as the best identifier token within the result. To store a single token to reference the identity, use the package token.
Labels
Labeling your identifiers helps minimize confusion when managing large numbers of identifiers, especially if you have more than one identifier of the same type.
To label an identifier, simply use the label option when invoking the call:
xxxxxxxxxxmy_identity = Identity( # labels help differentiate the tokens in the result Identifier('email', 'someone.special@somedomain.com', label="personal email"), Identifier('email', 'someone.special@someotherdomain.com', label="work email"),)This yields the following output:
xxxxxxxxxx{ "package_token": "e67529f593120f5b141b0920199ca6aabfea864c735ad6e3a1625227da735137", "tokens": [ { "private": "15ba6cd3b7f2618e680180706ae65850093ee165d36fb743c4d64ec3a51bd823", "adara": "4447b2c72b9aa03977af4b9f085feaf001587b652f36a914363d8eb709bc20bf", "my_consortium": "b84057a0bf979e28d53b846c2f3148a1f58e07a282f1bd768ce73a0fce347aef", "my_other_consortium": "8077ddc77cf8735dd6143d929f9f04deceec33e53331fe8466ad63934e33be3e", "type": "email", "label": "personal email" }, { "private": "b790e43743f7db5735e5b77034036bc040656b70dc969230a5ffeec182a10982", "adara": "e0732ffd3b6524bc204df41a479f8143ceb7675f03f4152bec4daf36fd920483", "my_consortium": "368405c8c20623bd234a5d242ae1b48806f9ee91513735dfc5c66671da7bc858", "my_other_consortium": "63ae761a793f944207c6a030c7b355ef9e407196786f071a3d4b0e038dc59d45", "type": "email", "label": "work email" } ]}Labels can be any string, so you can use something like a UUID to track tokens programmatically.
Cherry Picking Common Tokens
Generally, ADARA recommends including all the salts you may want to use for token creation in the configuration file. Alternately, in cases where you want to submit identity data to some identity graphs, while omitting it from others, you can cherry-pick a subset of common tokens for a subset of consortiums.
To limit token results for any identifier to only a subset of your defined common salts, use the common_tokens keyword argument in the Identifier instantiation:
xxxxxxxxxxmy_identity = Identity( # labels help differentiate the tokens in the result Identifier('email', 'someone.special@somedomain.com', label="personal email"), Identifier(email='someone.special@someotherdomain.com', label="work email", common_tokens=['adara', 'my_consortium'] ),)This yields the following output:
xxxxxxxxxx{ "package_token": "8736afea56e62d978360b8f304ea6f33c692203ba91649aaf1226eb0601ef353", "tokens": [ { "private": "15ba6cd3b7f2618e680180706ae65850093ee165d36fb743c4d64ec3a51bd823", "adara": "4447b2c72b9aa03977af4b9f085feaf001587b652f36a914363d8eb709bc20bf", "my_consortium": "b84057a0bf979e28d53b846c2f3148a1f58e07a282f1bd768ce73a0fce347aef", "my_other_consortium": "8077ddc77cf8735dd6143d929f9f04deceec33e53331fe8466ad63934e33be3e", "type": "email", "label": "personal email" }, { "private": "b790e43743f7db5735e5b77034036bc040656b70dc969230a5ffeec182a10982", "adara": "e0732ffd3b6524bc204df41a479f8143ceb7675f03f4152bec4daf36fd920483", "my_consortium": "368405c8c20623bd234a5d242ae1b48806f9ee91513735dfc5c66671da7bc858", "type": "email", "label": "work email" } ]}Sending Data to ADARA
To send your tokens to the ADARA Privacy API, use the AdaraPrivacyApiStreamer class.
You'll need to specify several of the optional settings in the configuration file for this. Contact ADARA's provisioning team to set up a configuration file to send your privacy tokens to the ADARA Privacy API. ADARA will provide the client secrets, pipeline IDs, API endpoints, etc. to match your use case. |
The following sample code loops over the tokens stored in a file and sends them to the ADARA Privacy API:
xxxxxxxxxxfrom adara_privacy import Identity, Identifier, AdaraPrivacyApiStreamer# create instance of an API streameradara_api = AdaraPrivacyApiStreamer()# create an identity instancemy_identity = Identity( # labels help differentiate the tokens in the result Identifier('email', 'someone.special@somedomain.com', label="personal email"), Identifier(email='someone.special@someotherdomain.com', label="work email", common_tokens=['adara', 'my_consortium'] ),)# push the identity tokens to ADARAadara_api.save(my_identity)