User Profile Data

Identity Providers return user profile data along with session information when a user authenticates successfully. You can use the user profile information to help the user by filling out sign-up or registration forms, as well as to recognize each user and learn more about them in order to give the user a tailored experience.

The Janrain servers return normalized user profile data in standard POCO (Portable Contacts) format. (See http://portablecontacts.net/. Field names and definitions start here: http://portablecontacts.net/draft-spec.html#anchor16.) This makes it easier for you to parse and use the profile data without having to learn about each provider’s data format.

Normalized User Profile Data ¶

Janrain Engage converts the data we receive in one of the diverse data formats returned by the Identity Providers into a single standard format. We call this process normalization. Programmers save time immediately by learning only one format, and repeatedly by not needing to update their code when new providers are added or providers change their data format.

Personal Data Fields ¶

This section outlines the fields in the normalized profile structure. The Availability column shows whether or not all providers include the field in their profile data responses.

Key	Description	Availability
`identifier`	The user’s `OpenID` URL. Use this value to sign the user in to your website. This field is always present.	Guaranteed.
`providerName`	A human-readable name of the authentication provider that was used for this authentication. For well-known providers, Janrain Engage sends values such as “Google”, “Facebook”, and “MySpace”; “Other” is sent for other providers. New provider names are added over time.	Guaranteed.
`primaryKey`	The primary key of the user in your database. Only present if you are using the mapping API.	Guaranteed, if a mapping exists.
`displayName`	The name of this Contact, suitable for display to end-users.	Available from most providers, with user consent.
`preferredUsername`	The preferred username of this contact on sites that ask for a username.	Available from most providers, with user consent.
`name`	A dictionary of name parts. See the name field section for details.	Available from most providers, with user consent. Yahoo! returns only a full name, not a first name or last name field.
`gender`	The gender of this person. Canonical values are `female` and `male`, but may be any value.	Available from most providers, with user consent.
`birthday`	Date of birth in YYYY-MM-DD format. Year field may be 0000 if unavailable.	Available from most providers, with user consent.
`utcOffset`	The offset from UTC of this Contact’s current time zone, as of the time this response was returned. The value MUST conform to the offset portion of xs:dateTime, for example, -08:00. Note that this value MAY change over time due to daylight saving time, and is thus meant to signify only the current value of the user’s timezone offset.	Available from most providers, with user consent.
`email`	An email address at which the person may be reached.	Available from most providers, with user consent. Not available from Twitter, LinkedIn, and MySpace.
`verifiedEmail`	An email address at which the person may be reached.	Available from Google, Facebook, Yahoo!, PayPal, Foursquare, and SalesForce.
`URL`	The URL of a webpage relating to this person.	Available from most providers, with user consent.
`phoneNumber`	A phone number at which the person may be reached.	Available from most providers, with user consent.
`photo`	The URL to a photo (GIF/JPG/PNG) of the person.	Available from most providers, with user consent.
`address`	See the address field section for details.	Available from most providers, with user consent.
`limitedData`	A boolean value, `true` if Janrain Engage was able to retrieve only limited public data from the user’s profile (for example, because the login session has expired or the user logged out from their account). If Janrain Engage succeeded in retrieving complete set of data, this field will be missing or set to `false`.	Provided by Facebook only.

The name Field ¶

The components of the end user’s real name. Providers may return just the full name, as a single string in the formatted sub-field, or they may return just the individual component fields, using the other sub-fields, or they may return both. If a provider returns both variants, they should describe the same name, with the formatted name indicating how the component fields should be combined.

Key	Description
`formatted`	The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (for example, Mr. Joseph Robert Smarr, Esq.). This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.
`familyName`	The family name of this Contact, or “Last Name” in most Western languages (for example, Smarr given the full name Mr. Joseph Robert Smarr, Esq.).
`givenName`	The given name of this Contact, or “First Name” in most Western languages (for example, Joseph given the full name Mr. Joseph Robert Smarr, Esq.).
`middleName`	The middle name(s) of this Contact (for example, Robert given the full name Mr. Joseph Robert Smarr, Esq.).
`honorificPrefix`	The honorific prefix(es) of this Contact, or “Title” in most Western languages (for example, Mr. given the full name Mr. Joseph Robert Smarr, Esq.).
`honorificSuffix`	The honorific suffix(es) of this Contact, or “Suffix” in most Western languages (for example, Esq. given the full name Mr. Joseph Robert Smarr, Esq.).

The address Field ¶

Key	Description
`formatted`	The full mailing address, formatted for display or use with a mailing label.
`streetAddress`	The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information.
`locality`	The city or locality component.
`region`	The state or region component.
`postalCode`	Postal code or zipcode.
`country`	The country name component.

Provider Specific Fields ¶

Some Identity Providers return fields specific only to them. These fields will be present in the ‘provider’ dictionary keyed by the provider name.

Key	Description	Provider
`userType`	The user type.	Salesforce
`active`	Boolean, true means the user is active, false means the user is not active.	Salesforce
`locale`	User’s locale.	Salesforce
`type`	One of brand, celebrity, or user. Users can establish their type when following relationships with celebrities.	Foursquare
`relationship`	The relationship of the acting user (me) to this user (them).	Foursquare
`pings`	Whether Foursquare receive pings from this user, if they have a relationship.	Foursquare
`positions`	Collection of positions each with isCurrent boolean and name (employer name) for each.	Linkedin
`verifiedAccount`	‘true’ if the PayPal account has been verified, ‘false’ if the account is unverified.	PayPal
`occupation`	The user’s occupation.	Mixi
`favoriteThings`	List of the user’s favorite things, broken down by ‘order’ (numerical value), ‘type’ (category), and ‘value’ (text).	Mixi
`bloodType`	The user’s blood type.	Mixi
`friendshipList`	A list of the user’s friends on the Renren site. This is part of the extended profile data.	Renren
`photos`	The photos the user has uploaded to the Renren site. This is part of the extended profile data.	Renren

Facebook Specific Fields ¶

We describe these fields separately because they have a different structure, each field contains a number of sub-fields or elements. Be sure to look at Facebook’s Extended Profile Resource page.

Key	Sub-Fields	Type	Description
`albums`		`plural`	A set of fields describing a photo album saved somewhere on Facebook.
	`id`	`string`	The Facebook id of the album, a string of numbers.
	`name`	`string`	The text name of the album.
	`privacy`	`string`	The privacy setting of the album, such as public, friends, or custom.
	`type`	`string`	The type of Facebook post that contains the album (or link to the album), such as normal, wall, or profile.
`games`		`plural`	A set of fields describing a game. Can be any sort of game.
	`name`	`string`	The text name of the game.
	`category`	`string`	A Facebook category, such as interest.
	`id`	`string`	The Facebook id of the game, a string of numbers.
`groups`			A set of fields describing a Facebook group.
	`name`	`string`	The name of the Facebook group.
	`id`	`string`	The Facebook id of the group, a string of numbers.
`videos`			A set of fields describing a video.
	`id`	`string`	The Facebook id of the video, a string of numbers.
	`description`	`string`	A text string describing the video.
	`picture`	`url`	The URL to a thumbnail picture of the video.
	`icon`	`url`	The URL to an icon for the video.
	`embed_html`		A block of html code that you can embed on your page to play the video on your site. See the sample following this table.
	`source`	`url`	The source for the video.

Video Player ¶

This is a sample of the code for the video player. Facebook might change this, so do not consider this completely accurate. This sample is to give you an idea of how this feature works.

"embed_html": "<object width=\"386\" height=\"392\" ><param name=\"allowfullscreen\" value=\"true\" /><param name=\"movie\" value=\"http://www.facebook.com/v/123456789123456\" /><embed src=\"http://www.facebook.com/v/123456789123456\" type=\"application/x-shockwave-flash\" allowfullscreen=\"true\" width=\"386\" height=\"392\"></embed></object>",

Provider Guide ¶

The Provider Guide gives a complete list of Identity Providers and the features supported by each. Providers are added on a regular basis to fulfill customer’s needs and to extend their reach.