Add more opts

By default, Hosted Login comes with a single consent opt called marketingConsent. You can add more consent or preference opts as needed to fit your business requirements. Additional opts in Hosted Login screen

To do this, follow the steps below.

1. Update the schema

For each new consent or preference opt you’d like to collect, you must create an attribute or object in the schema to store the opt data. This can be done via API call.

In this step, you’ll make RESTful API calls to the Identity Cloud using your platform or language of choice. We provide complete sample calls in cURL format.

New to making API calls?

You can add a new attribute or object to the schema by making an API call to the /entityType.addAttribute endpoint using the POST method.

  • The base URL for this call is your Registration Domain.

    Find my Registration Domain

  • This call requires Basic Authorization. To create the authorization code for this call, your application owner Client Id and Secret must be combined with a colon in between (id:secret) and then base64 encoded.

    Find my application owner Client Id and Secret
    How to create the authorization code in Postman

SAMPLE CALL:

curl -X POST \
	https://my-registration-domain.janraincapture.com/entityType.addAttribute \
	-H 'Authorization: Basic AUTHORIZATION CODE' \
	-H 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode type_name=user \
	--data-urlencode attr_def='{"name":"myNewAttribute","type":"boolean"}'

Note the attr_def value used in this call:

'{"name":"myNewAttribute","type":"boolean"}'

This is the attribute definition in JSON format.

  • Specifying the attribute name as myNewAttribute places a new attribute named “myNewAttribute” at the root level of the schema. If you’d like to do something different, see the additional sample attr_defs below.
  • This attribute definition creates a boolean attribute, which can store a user’s opt value of true or false. You may need to create a different type of attribute with different constraints. For more information, see Managing Your Schema.

Tips for what to add to the schema

Below are some simple scenario-based suggestions for customizing the schema in a clean, organized way. A sample attr_def value for your API call is provided for each.

  • If you’re adding another consent opt with metadata like the default Marketing Consent, you can add a new object into the consents object and give it an appropriate name (e.g. personalizedAds). This way all your consents are consistent and organized under consents.
    attr_def='{
    	"name":"consents.personalizedAds",
    	"type":"object",
    	"attr_defs":[
          {"name":"clientId","type":"string","length":32},
          {"name":"context","type":"string","length":100},
          {"name":"granted","type":"boolean"},
          {"name":"type","type":"string","length":8},
          {"name":"updated","type":"dateTime"}
    	]
    }'
    

IMPORTANT! If the user’s consent is required in order to authenticate into your site or app, you must use the above schema format.

To be more specific: In order for the consent to work with Hosted Login’s Consents authorization rule, it must match all of the following schema requirements:

  • It must be a child of the “consents” object ("name": "consents.myNewConsent")
  • It must be an object-type attribute ("type":"object")
  • It must contain a boolean attribute named “granted”, and this is where the consent value must be stored ("attr_defs":[{"name":"granted","type":"boolean"}])
  • If you’re adding another consent opt without all the metadata, you can add a new boolean attribute into the consents object and give it an appropriate name. This way all your consents are organized under consents and no unnecessary attributes are added.
    attr_def='{"name":"consents.personalizedAds", "type":"boolean"}'
    

IMPORTANT! If the user’s consent is required in order to authenticate into your site or app, use the following attr_def instead:

attr_def='{"name":"consents.personalizedAds", "type":"object", "attr_defs":[{"name":"granted","type":"boolean"}]}'

See the previous orange note for more details.

  • If you’re adding an opt that is not a consent (e.g. a newsletter subscription) and does not require additional metadata, you can add a new boolean attribute to the root level of the schema (e.g. newsletterOpt).

    attr_def='{"name":"newsletterOpt", "type":"boolean"}'
    
  • If you’re adding multiple opts that are not consents and should be grouped together, you can add a new object to the root level of the schema (e.g. subscriptions) and add all related opts into it as boolean attributes (e.g. newsletterOpt, couponOpt, eventOpt).

    attr_def='{
    	"name":"subscriptions",
    	"type":"object",
    	"attr_defs":[
          {"name":"newsletterOpt","type":"boolean"},
          {"name":"couponOpt","type":"boolean"},
          {"name":"eventOpt","type":"boolean"}
    	]
    }'
    
  • If you’re adding an opt that is not a consent and you want to include metadata about it, you can add a new object to the schema (e.g. newsletterSubscription). Your object should contain a boolean attribute to store the opt value (e.g. optValue), along with other attributes needed to store metadata about the opt (e.g. updated).

    attr_def='{
    	"name":"newsletterSubscription",
    	"type":"object",
    	"attr_defs":[
          {"name":"optValue","type":"boolean"},
          {"name":"updated","type":"dateTime"}
    	]
    }'
    

Your own customizations may be different depending on your specific use cases. If you still have questions about customizing the schema, please reach out to your Akamai Representative.

2. Add field(s) to the flow

Once your schema attributes are in place, the next step is to create fields in the flow. Each field allows you to collect the end user’s consent or preference and map it to a schema attribute in the user record.

You can add new fields via the Identity Cloud Console:

  1. Click on your application in the left column navigation
  2. Click to open REGISTRATION BUILDER Registration Builder in Console
  3. Click the Actions menu ( ) next to the flow you want to update and select Edit Edit Flow in Console
  4. On the Edit page, go to the FIELDS tab
  5. Find the field called marketingConsent. By default, fields are listed in alphabetical order by Field Name. You can use the pagination controls in the bottom-right corner of the table, or sort by column if needed.
  6. Click the Copy Field icon ( ) for this field Copy marketingConsent field in Console
  7. In the pop-up, replace the suggested field name (e.g. marketingConsent_copy) with the real name you want to use to identify the new field (e.g. personalizationConsent, subscriptionOpt, etc.) and click the SAVE button Copy a field in Registration Builder
  8. A success message will appear in the bottom-right corner of the screen (e.g. personalizationConsent successfully created). Click VIEW to go to your new field. Copy a field message in Registration Builder
  9. In the new field’s configuration page, the Name and Field Type are pre-filled and cannot be changed. However, note that the new field’s Schema Attribute matches the field you copied from. In order to map this field to the correct schema attribute, click SELECT NEW SCHEMA ATTRIBUTE Select schema attribute in Registration Builder
  10. In the pop-up, select your schema (e.g. user) and then select the Attribute this field should map to (e.g. consents.personalization.granted). Select schema attribute in Registration Builder
  11. Update the Label and Tip text. This is the text that will display to end users in the Hosted Login screen(s). Label and Tip text in Registration Builder

    Note that Ignore updates submitted to this field is selected. Ignore updates in Registration Builder This prevents Hosted Login from trying to write the user-submitted value directly to the user record.

    • If you will be writing the opt + metadata to the user record, keep this selected. The logic you implement in the next section will write the opt value for you.
    • If you are NOT planning to write any additional metadata about this opt, un-check this field. This will allow Hosted Login to write the opt value directly to the user record.
  12. If you would like this opt field to be required for the end user (cannot be left unchecked), add this as a new validation into the Data Validations section. Otherwise, you can leave this section as-is. Required validation in Registration Builder
  13. In the Forms section, click ADD FORM to select the form(s) you’d like this field to appear on. Add to Forms in Registration Builder
  14. IMPORTANT! You must click the SAVE CHANGES button at the bottom of the Edit Field page in order to save all your new field configurations.

Example of new personalizationConsent opt in manageProfile_privacyForm: New opt in Hosted Login screen

3. Add logic to write metadata (if applicable)

You should now have a field in the flow to collect the user’s consent, and an attribute in the schema to store the user’s consent. If this is all you need, you’re done!

But what if you need to write additional data about the opt to the user record? Additional data written to user record

For this, please reach out to your Akamai Identity Cloud representative. The logic that tells Hosted Login what to write into the user record can be modified by the Akamai Identity Cloud Professional Services team to support your specific needs.