Adding Claims to your client request
To add Claims to your client request, use the serializer offered by the Ambient Data Framework APIs, or create your own serializer, to turn your Claim(s) (URI-value pairs) into one or more cookies in JSON format on the client side. You then attach the JSON cookie(s) to the client's request yourself.
Procedure
- First, decide which Claims you wish to attach to your client's request. Claims must be presented to the serializer in the form of URI-value pairs. The Claims you present can be completely new Claims, or existing Claims with new values. The server ignores any URIs that are not configured as Globally Accepted Claims on the server side.
The value part of the URI-value pair must be one of the following allowed primitive or complex types:
- A string
- An integer
- A double
- A float
- A long
- A Boolean
- An array of items of one of the allowed primitive or complex types.
- A property-value map whose values are any of the allowed primitive or complex types.
- If you have access to the API from your client, call the Ambient Data Framework API to serialize your Claim(s) into one or more cookies:
- If you use the .NET API, pass your URI-value pairs as a
System.Collections.Generic.IDictionary<object,object>argument to theSerializeClaimsmethod of the classTridion.ContentDelivery.AmbientData.ClaimCookieSerializer.Your return value is an object of type
System.Collections.Generic.List<ClaimsCookie>, whereClaimsCookiehas the fully qualified class nameTridion.ContentDelivery.AmbientData.ClaimsCookie. If you use the Java API, pass your URI-value pairs as a
Map<URI,Object>argument to theserializeClaimsmethod of the classcom.tridion.ambientdata.claimstore.cookie.ClaimCookieSerializer.Your return value is an object of type
List<ClaimsCookie>, whereClaimsCookiehas the fully qualified class namecom.tridion.ambientdata.claimstore.cookie.ClaimsCookie.
For more information, refer to the Content Delivery API reference documentation for .NET and Java.
The API produces one or more cookies to attach to your client request. - If you use the .NET API, pass your URI-value pairs as a
- Alternatively, if you do not have access to the API from your client, create your own serializer in your own client language (such as JavaScript, PHP or Python). The serializer has the following functional description:
- It turns your URI-value pairs into output in JSON format defined for these cookies.
- It Base64-encodes the JSON-formatted output.
- If the resulting Base64-encoded output is larger than 4000 bytes, it chops up the output into multiple cookies of 4000 bytes (plus a final cookie containing the remainder).
- It gives the cookies the names COOKIE_NAME.1, COOKIE_NAME.2 and so on, where COOKIE_NAME defaults to the
TAFContext. You can change the default cookie name if you have a pressing reason to do so; if you do, the names of the cookies you produce must also change.
- If the total size of all cookies combined results in a request header size that is larger than your web application server can handle, the request will result in a 400 Bad Request error. If this is the case, configure a larger request header size. Consult the documentation of your web application server for more information.
- Attach the cookie(s) to your request using, for example, JavaScript, PHP or Python. You must do this yourself because the method of attaching depends on the specific technology you are using.
- Send your request. The cookie(s) included in the request are now sent and deserialized on the receiving end.
Note that the serialization and deserialization process may cause a change in the data type of the value you passed. Specifically:
Original data type long An input value of type long will become an output value of type integer if the value is small enough to fit into an integer. To get your long back, on the receiving end, cast such a number back to long after deserialization. float or double An input value of type float or double will become an output value of type integer if it is a whole number and you leave out the fractional part. To ensure that deserialization gives you a float or double back, add trailing zeros when your serialize. double An input value of type double will become an output value of type float if the precision is low enough to fit into a float. Prevent this by adding extra zeros when you serialize, or by explicitly casting the output value back to double after deserialization. array An input value of type array (that is, a simple, non-resizable array) will become an output value of type ArrayList(Java deserialization) orList(.NET deserialization) . You can get the original array back by using the.toArraymethod of theArrayListoutput object, or the.ToArraymethod of theListoutput object.map An input value that is a property-value map will become an output value of type HashMap(Java deserialization) orDictionary(.NET deserialization) .