Janrain 使用文檔

Documentation

Additional Documentation:

• Engage for Android - Library for Android app support
• Engage for iOS - Library for native iOS app support
• Provider Guide - Features supported by each provider
• Social Sharing API - Allows users to post acitivty updates to popular social networks

In This Document:

Introduction to Janrain Engage

• Overview
• User Interaction Flow

Integrating The Sign-In Interface

• The Sign-In Interface
• Setting the default provider
• Localization
• Your token_url

Authentication and Profile Data: Using the API

• Profile Data
• Mappings
• API Documentation
  • API request format
  • API response format
  • API error responses
  • auth_info API call
  • get_contacts API call
  • get_user_data API call
  • set_status API call
  • map API call
  • unmap API call
  • mappings API call
  • all_mappings API call
  • activity API call
  • analytics_access API call
  • set_auth_providers API call
  • providers API call

Overview

Janrain makes it easy to add OpenID and other authentication APIs to your website. We help you add authentication from providers like Google, Facebook, Twitter, Yahoo! and Windows Live ID, making it extremely simple for users to get in and start using your web application. It runs on our servers in the cloud and is accessed via simple, restful API calls. Janrain Engage is a proxy between your website and the OpenID provider, and is completely transparent to the end user. Adding Janrain Engage to your website doesn't require any changes to your database, and its only requirements are the ability for your servers to make outbound HTTPS calls and to parse JSON or XML.

Janrain Engage Flow

Below is a step-by-step diagram that shows how a user will sign in to your website using Janrain Engage, including the appropriate integration points.

The Sign-in Interface

Janrain Engage uses javascript to add a user friendly sign-in box to your website. Below is a sample of the sign-in widget. We'll supply you with javascript customized to show it on your web site:

Additionally, you may embed the interface directly into a page on your site without using the javascript popup. If you would like to disable the pre-existing "Select one of these third-party accounts" at the top of the embedded display, include the parameterflags=hide_sign_in_with in your embedded iframe's src URL.

Sign-In Interface Default Provider

By default, users that have never signed in to your site will see the Janrain Engage sign-in interface as pictured above, with all your providers shown. To set a default provider in this case, you can set RPXNOW.default_provider in your JavaScript to one of the following values, depending on which providers you have enabled for your relying party:

"aol"
"facebook"
"google"
"live_id"
"myspace"
"openid"
"yahoo"
"flickr"
"livejournal"
"myopenid"
"verisign"
"wordpress"
"blogger"
"hyves"
"netlog"
"twitter"
"linkedin"
"paypal"
"salesforce"
"orkut"
"vzn"
"foursquare"

For example:

RPXNOW.default_provider = "openid";

To cause the widget to display the provider list even if they have logged in before, setRPXNOW.flags="show_provider_list".

Sign-In Interface Localization

You can set the language for the sign-in interface to one of the following:

ar bg cs da de el en es fi foo fr he hr hu id it ja lt nb-NO nl 
nl-BE nl-NL no pl pt pt-BR pt-PT ro ru sk sl sr sv sv-SE th uk zh zh-CHT 

If you'd like to use a language that is missing from this list or if you would like to improve our existing translations, please let us know.

Setting the language for the popup

Set RPXNOW.language_preference in the javascript in your page.

For example:

RPXNOW.language_preference = 'es';

Setting the language for the embedded widget

Add the parameter "language_preference=lang" to your embedded iframe's src URL, where lang is any of the language codes listed above.

Your token_url

When configuring the sign-in interface, you supply a token_url parameter. This is where the user will POST their token after completing the authentication process. You must extract the token and pass into the auth_info API call.

Parameter	Type	Description
token	string	The token used for the auth_info API call

If the user cancels the OpenID sign-in transaction, they will make a POST to your token_url without the token parameter.

Note: You can pass state through the Janrain Engage authentication transaction by adding query parameters to your token_url.

Profile Data

Janrain Engage can request profile and registration data from the user using the Simple Registration OpenID extension, the HCard microformat, and soon via the new Portable Contacts protocol. This information may be used to aid in new user registration, and profile/contact information syncing.

Source: Simple Registration OpenID Extension

The Simple Registration (SREG) OpenID extension provides a mechanism for providers to send a small set of registration data the relying party during the OpenID transaction. SREG is currently supported by many of the major independent OpenID providers, and will likely soon be supported by the major consumer providers as well. Nine fields are defined in the Simple Registration schema: nickname, email, fullname, dob, gender, postcode, country, language, and timezone. Data fields are sent with the user's consent, and their presence is purely for user convenience.

Source: Attribute Exchange

OpenID Attribute Exchange (AX) is an OpenID service extension for exchanging identity information between endpoints. Janrain Engage currently support AX for fetching verified email addresses from Google's OpenID provider.

Source: hCard

hCard is a simple, open, distributed format for representing people, companies, organizations, and places, using a 1:1 representation of vCard properties and values in semantic HTML or XHTML. hCard is commonly embedded in OpenID pages to provide machine readable public identity data. Many OpenID providers automatically mark their users' profile pages up with hCard data, which can be useful to you in user registration and/or profile syncing.

Source: Facebook

If you have enabled Facebook (FB) login for your Janrain Engage sites, we'll provide you with some standard profile fields that the Facebook platform makes available through their API.

Normalizing Sources

For your convenience, Janrain Engage normalizes profile data from our sources into a standardized format. This makes it easy for you to parse and use the profile data without having to learn about the different sources and their individual schemas.

Personal Data Fields

Outlined below are the fields that are available in the normalized profile structure.

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	Primary key of the user in your database. Only present if you are using the mapping API.	guaranteed if amapping 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.
gender	The gender of this person. Canonical values are 'male', and 'female', 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, e.g. -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, or MySpace.
verifiedEmail	An email address at which the person may be reached.	Available from Google, Facebook, Yahoo! and PayPal.
url	URL of a webpage relating to this person.	Available from some providers, with user consent.
phoneNumber	A phone number at which the person may be reached.	Available from some providers, with user consent.
photo	URL to a photo (GIF/JPG/PNG) of the person.	Available from some providers, with user consent.
address	See the address field section for details	Available from some providers, with user consent.
limitedData	true if Janrain Engage was able to retrieve only limited public data from the user's profile (e.g., 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.	Used only with Facebook.

The name field

The components of the person'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 both variants are returned, they SHOULD be describing 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 (e.g. 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 (e.g. Smarr given the full name Mr. Joseph Robert Smarr, Esq.).
givenName	The given name of this Contact, or "First Name" in most Western languages (e.g. Joseph given the full name Mr. Joseph Robert Smarr, Esq.).
middleName	The middle name(s) of this Contact (e.g. Robert given the full name Mr. Joseph Robert Smarr, Esq.).
honorificPrefix	The honorific prefix(es) of this Contact, or "Title" in most Western languages (e.g. Mr. given the full name Mr. Joseph Robert Smarr, Esq.).
honorificSuffix	The honorific suffix(es) of this Contact, or "Suffix" in most Western languages (e.g. 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 providers return fields specific only to them. These fields will be present in the 'provider' dictionary keyed by the provider name.

key	description	provider(s)
userType	The user type	salesforce
active	Is the user active? 'true' or 'false'	salesforce
locale	User's locale	salesforce
type	One of brand, celebrity, or user. Users can establish 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

Mappings

Janrain Engage allows customers to associate a user account record in the customer’s database with one or more user identities in Janrain Engage. We call these associations Mappings.

Mappings can connect a user who has just authenticated with a social network to his or her legacy local account. Mappings may also be used to link multiple social networking accounts to a single user, either through a front-end login process or as a feature associated with a user profile. The Janrain Engage mapping API permits multiple methods of user account mapping. Mappings help you add social sign-in to your existing user accounts without changing your database schema. The Mapping API also helps you implement the best practice of allowing multiple social identities per user, which gives the end user total control of their identity by letting them switch their identity provider as their needs change.

You probably have a "users" or "accounts" table in your database. The mapping API lets you associate the primary key of an existing user with an identity provider’s identifier, and store that mapping on the Janrain Engage server. When a mapping exists for a user, Janrain Engage returns both the primary key for the user and the associated provider’s indentifier in the auth_info call. You then use the primary key to figure out which account to sign the user into on your site.

New mappings are created with the map API call. Before using the map API call to save a primary key to identifier mapping, you must first know who the user is on your site, and have a record for them in your users or accounts table. This means that the user is either already logged in with a legacy account, or they have been verified using Janrain Engage and you have created a new record for them in the database but haven't yet stored that mapping anywhere. Either way, new mappings are generally created right after a user has verified their identity with Janrain Engage and you have extracted their identifier via the auth_infoAPI call.

The image below represents a website using Janrain Engage with a Users table that has a primary key called "id". A user has bound three different provider identities to his account, and because the website is using the mapping API he may use any one of his mapped accounts to sign in as the BrianMan692 user.

After the mapping is made, when the user signs in with his brian.myopenid.com OpenID, an auth_info response including the primaryKey will be returned. Use the value of the primaryKey field to sign the user in as BrianMan692.

{
  "profile": {
  "identifier": "http:\/\/brian.myopenid.com\/",
  "primaryKey": "17"
  },
  "stat": "ok"
}
  

Janrain Engage API

The following sections describe in detail the back-channel API calls you will make to the Janrain Engage servers. The next section discusses the general request and response formats, and error cases that each API call adheres to.

Request Format

Each API call into Janrain Engage is made as an HTTP POST to the base URL list below. Additionally, each call has a method name, and a set of required and/or optional parameters.

Base API URL

https://rpxnow.com/api/v2/method-name

Response Format

Janrain Engage formats API responses in either XML or JSON. It is required that you include the format query parameter in your request URL.

Parameter	Required?	Description
format	yes	'json' or 'xml'

Error Responses

If an irrecoverable error occurs during the API call, Janrain Engage will return an error response with a code and a message.

Error Code	Description
-1	Service Temporarily Unavailable
0	Missing parameter
1	Invalid parameter
2	Data not found
3	Authentication error
4	Facebook Error
5	Mapping exists
6	Error interacting with a previously operational provider
7	Engage account upgrade needed to access this API
8	Missing third-party credentials for this identifier
9	Third-party credentials have been revoked
10	Your application is not properly configured
11	The provider or identifier does not support this feature
12	Google Error
13	Twitter Error
14	LinkedIn Error
15	LiveId Error
16	MySpace Error
17	Yahoo Error
18	Domain already exists
19	App Id not found
20	Orkut Error

Here's a sample error response:

JSON

{
  "err": {
    "msg": "Data not found",
    "code": 2
  },
  "stat": "fail"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='fail'>
  <err msg='Data not found' code='2'/>
</rsp>

auth_info

The auth_info call is used in your token_url code, and is called after extracting the token. Use the auth_info call to get information about the user currently signing in to your web application.

auth_info - Request

API URL
https://rpxnow.com/api/v2/auth_info
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key
token	yes	The token parameter received at your "token_url" in step 5.
extended	no	'true' or 'false'(default). Return the extended Simple Registration and HCard data in addition to the normalized Portable Contacts format.
tokenUrl	no	Validate the specified token URL value against the token URL that was originally sent. See 'Token URL mismatch' below for more details.

auth_info - Response

The auth info contains all the information Janrain Engage knows about the user logging into your website.

Parameter	Type	Description
profile	dictionary	A dictionary of fields forming the user's profile. This data may have been obtained through SREG, HCard, but is represented in the standard Portable Contacts schema. Profile data documentation.
accessCredentials	dictionary	If the user logged in with a provider that allows account access after authentication, this will be present and contain the user's authorization credentials. A field named 'type' will describe the type of access available, and be one of 'OAuth', 'Facebook', or 'WindowsLive'. For OAuth, the provided fields are named 'oauthToken' and 'oauthTokenSecret', representing the OAuth access token. For Facebook, the provided fields are named 'uid', 'sessionKey', and 'expires'. For WindowsLive, the provided field is named 'eact', which contains the user's delegated authentication consent token.
merged_poco	dictionary	Merged Portable Contacts data will be present here if theextended request argument was 'true' and extended profile data were available.
friends	array	the user's friends' identifiers will be present here if theextended request argument was 'true' friends data were available.
provider	dictionary	Provider specific fields will be present here if the extendedrequest argument was 'true' and the provider returns additional fields which do not conform to the Portable Contacts spec. The data is returned as a dictionary of fields, keyed by provider name.

JSON

{
  "profile": {
    "displayName": "brian",
    "preferredUsername": "brian",
    "url": "http:\/\/brian.myopenid.com\/",
    "providerName": "Other",
    "identifier": "http:\/\/brian.myopenid.com\/"
  },
  "stat": "ok"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'>
  <profile>
    <displayName>
      brian
    </displayName>
    <identifier>
      http://brian.myopenid.com/
    </identifier>
    <preferredUsername>
      brian
    </preferredUsername>
    <providerName>
      Other
    </providerName>
    <url>
      http://brian.myopenid.com/
    </url>
  </profile>
</rsp>

auth_info - Token URL mismatch

If the tokenUrl parameter you specified does not match the token URL to which the token was originally sent, you will receive this error response:

JSON

{
  "err": {
    "msg": "Token URL mismatch: (your tokenUrl parameter) (original token URL)",
    "code": 3
  },
  "stat": "fail"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='fail'>
  <err msg='Token URL mismatch: (your tokenUrl parameter) (original token URL)' code='3'/>
</rsp>

get_contacts

Retrieve a list of contacts for an identifier in the Portable Contacts format.

The get_contacts call is made using the identifier returned in the auth_info call.

get_contacts - Request

API URL
https://rpxnow.com/api/v2/get_contacts
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key
identifier	yes	The identifier returned from the auth_info API call. Note: Only identifiers from Google, Yahoo, Windows Live, Facebook, MySpace, Twitter and LinkedIn are currently supported. Only Google and Windows Live provide a contact's email address. Google and Yahoo require additional setup from your Janrain Engage developer console.

get_contacts - Response

The get_contacts response contains a portable contacts response node with an entry for contact.

Parameter	Type	Description
response	dictionary	Portable Contacts data representing the address book contents for the identifier.

JSON

{
  "response": {
    "entry": [
      {
        "emails": [
          {
            "type": "other",
            "value": "[email protected]"
          }
        ],
        "displayName": "Bob Johnson"
      },
      {
        "emails": [
          {
            "type": "other",
            "value": "[email protected]"
          }
        ],
        "displayName": "Cindy Smith"
      },
      {
        "emails": [
          {
            "type": "other",
            "value": "[email protected]"
          }
        ],
        "displayName": "Fred Williams"
      },
      {
        "emails": [
          {
            "type": "other",
            "value": "[email protected]"
          }
        ]
      },
      {
        "emails": [
          {
            "type": "other",
            "value": "[email protected]"
          }
        ],
        "displayName": "Mary Jones"
      },
      {
        "emails": [
          {
            "type": "other",
            "value": "[email protected]"
          }
        ],
        "displayName": "Patricia Green"
      }
    ],
    "startIndex": 1,
    "itemsPerPage": 5,
    "totalResults": 5
  },
  "stat": "ok"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'>
  <response>
    <startIndex>
      1
    </startIndex>
    <itemsPerPage>
      5
    </itemsPerPage>
    <totalResults>
      5
    </totalResults>
    <entry>
      <displayName>
        Bob Johnson
      </displayName>
      <emails>
        <email>
          <type>
            other
          </type>
          <value>
            [email protected]
          </value>
        </email>
      </emails>
    </entry>
    <entry>
      <displayName>
        Cindy Smith
      </displayName>
      <emails>
        <email>
          <type>
            other
          </type>
          <value>
            [email protected]
          </value>
        </email>
      </emails>
    </entry>
    <entry>
      <displayName>
        Fred Williams
      </displayName>
      <emails>
        <email>
          <type>
            other
          </type>
          <value>
            [email protected]
          </value>
        </email>
      </emails>
    </entry>
    <entry>
      <emails>
        <email>
          <type>
            other
          </type>
          <value>
            [email protected]
          </value>
        </email>
      </emails>
    </entry>
    <entry>
      <displayName>
        Mary Jones
      </displayName>
      <emails>
        <email>
          <type>
            other
          </type>
          <value>
            [email protected]
          </value>
        </email>
      </emails>
    </entry>
    <entry>
      <displayName>
        Patricia Green
      </displayName>
      <emails>
        <email>
          <type>
            other
          </type>
          <value>
            [email protected]
          </value>
        </email>
      </emails>
    </entry>
  </response>
</rsp>

set_status

Set the status message for the account corresponding to an identifier.

The set_status call is made using the identifier returned in the auth_info call. The status message will be set using the appropriate API for the specified identifier; for example, if the specified identifier is a Facebook identifier, Janrain Engage will make an API call to Facebook to set the status on the Facebook account.

set_status - Request

API URL
https://rpxnow.com/api/v2/set_status
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key
identifier	yes	The identifier returned from the auth_info API call.
status	yes	The status message to set. No length restriction on the status is imposed by Janrain Engage, however Twitter and LinkedIn limit status length to 140 characters. See the truncate parameter.
location	no	This is a string containing location data associated with the content being published. The string is latitude, followed by longitude, for example "37.4220 -122.0843". Valid values for latitude are -90.0 to +90.0, with North being positive. Valid values for longitude are -180.0 to +180.0 with East being positive. In the cases of invalid values in the location parameter, an invalid parameter exception is returned by the API. In the case of unsupported providers or users who have disabled location on their account with the provider, the location value will be silently ignored.
truncate	no	'true' (default) or 'false'. If 'true', truncate status when posting to providers which impose status length restrictions (currently Twitter, Yahoo, and LinkedIn).

set_status - Response

This method has no specific response - It returns an empty success response if it completes without error.

JSON

{
  "stat": "ok"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'/>

set_status - Provider support

set_status is currently supported for the following providers:

• Facebook
• LinkedIn
• Twitter
• MySpace
• Google
• Yahoo!

If the provider does not provide a user status or does not provide an API to update it, this error response will be sent by Janrain Engage:

JSON

{
  "err": {
    "msg": "The provider or identifier does not support this feature",
    "code": 11
  },
  "stat": "fail"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='fail'>
  <err msg='The provider or identifier does not support this feature' code='11'/>
</rsp>

map

Map an OpenID to a primary key. Future logins by this owner of this OpenID will return the mapped primaryKey in theauth_info API response, which you may use to sign the user in.

The map call is usually made right after a call to auth_info, when you already know who the user is because they are signed in to your website with their legacy (or existing) account.

map - Request

API URL
https://rpxnow.com/api/v2/map
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key
identifier	yes	The identifier returned from the auth_info API call.
primaryKey	yes	The primary key from your users table, as a string.
overwrite	no	'true'(default) or 'false'. If 'false', only create the mapping if one does not already exist for the specified identifier.

map - Response

This method has no specific response - It returns an empty success response if it completes without error.

JSON

{
  "stat": "ok"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'/>

unmap

Remove (unmap) an OpenID from a primary key, and optionally unlink your application from the user's account with the provider.

unmap - Request

API URL
https://rpxnow.com/api/v2/unmap
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key
identifier	w/o all_identifiers	The identifier currently mapped to the primaryKey.
all_identifiers	w/o identifier	'true' or 'false'(default). If true, all identifiers mapped to the primaryKey should be removed.
primaryKey	yes	The primary key from your users table, as a string.
unlink	no	'true' or 'false'(default). If 'true', unlink your application from the user's account with the provider. Only Facebook is currently supported.

unmap - Response

This method has no specific response - It returns an empty success response if it completes without error.

JSON

{
  "stat": "ok"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'/>

mappings

Get all stored mappings for a particular primary key

mappings - Request

API URL
https://rpxnow.com/api/v2/mappings
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key
primaryKey	yes	The primary key from your users table, as a string.

mappings - Response

JSON

{
  "stat": "ok",
  "identifiers": [
    "http:\/\/brian.myopenid.com\/",
    "http:\/\/brianellin.com\/"
  ]
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'>
  <identifiers>
    <identifier>
      http://brian.myopenid.com/
    </identifier>
    <identifier>
      http://brianellin.com/
    </identifier>
  </identifiers>
</rsp>

all_mappings

Get all stored mappings for a particular application

all_mappings - Request

API URL
https://rpxnow.com/api/v2/all_mappings
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key

all_mappings - Response

JSON

{
  "mappings": {
    "1": [
      "http:\/\/cygnus.myopenid.com\/"
    ],
    "2": [
      "http:\/\/brianellin.com\/",
      "http:\/\/brian.myopenid.com\/"
    ]
  },
  "stat": "ok"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'>
  <mappings>
    <mapping>
      <primaryKey>
        1
      </primaryKey>
      <identifiers>
        <identifier>
          http://cygnus.myopenid.com/
        </identifier>
      </identifiers>
    </mapping>
    <mapping>
      <primaryKey>
        2
      </primaryKey>
      <identifiers>
        <identifier>
          http://brianellin.com/
        </identifier>
        <identifier>
          http://brian.myopenid.com/
        </identifier>
      </identifiers>
    </mapping>
  </mappings>
</rsp>

activity

Post an activity update to the user's activity stream. Currently supported providers are:

• Facebook
• LinkedIn
• Twitter
• MySpace
• Yahoo!

Janrain Engage will make a best effort to use all of the fields submitted in the activity request, but note that how they get presented (and which ones are used) ultimately depends on the provider.

This API will work if and only if:

• Your Janrain Engage application has been configured to authenticate using the user's provider
• The user has already authenticated and has given consent to publish activity

Otherwise, you will be given an error response indicating what was wrong. Detailed error responses will also be given if theactivity parameter does not meet the formatting requirements described below.

activity - Request

API URL
https://rpxnow.com/api/v2/activity
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key
identifier	yes	The user's identifier as received in an auth_info API response
activity	yes	The activity structure, JSON-encoded. Be sure to URL-encode this value before submitting it.
truncate	no	'true' (default) or 'false'. If 'true', truncate activity update text when posting to providers which impose length restrictions (currently Twitter).
url_shortening	no	A boolean indicating whether to provide the entire url in the post/tweet, or the shortened version.
location	no	This is a string containing location data associated with the content being published. The string is latitude, followed by longitude, for example "37.4220 -122.0843". Valid values for latitude are -90.0 to +90.0, with North being positive. Valid values for longitude are -180.0 to +180.0 with East being positive. In the cases of invalid values in the location parameter, an invalid parameter exception is returned by the API. In the case of unsupported providers or users who have disabled location on their account with the provider, the location value will be silently ignored.

activity JSON structure

An activity request is a JSON object with the following attributes:

Key	Required?	Type	Description
url	yes	string	The URL of the resource being mentioned in the activity update
action	yes	string	A string describing what the user did, written in the third person. Examples: "wrote a restaurant review" "posted a comment" "took a quiz"
user_generated_content	no	string	A string containing user-supplied content, such as a comment or the first paragraph of an article that the user wrote. Note that some providers (Twitter in particular) may impose length restrictions on this value. See the truncate parameter.
title	no	string	The title of the resource being mentioned in the activity update. No length restriction on the status is imposed by Janrain Engage, however Yahoo truncates this value to 256 characters.
description	no	string	A description of the resource mentioned in the activity update
action_links	no	array	An array of objects, each having two attributes: text and href. An action link is a link a user can use to take action on an activity update on the provider. Example: action_links: [ {"text": "Rate this quiz result", "href": "http://example.com/quiz/12345/result/6789/rate"}, {"text": "Take this quiz", "href": "http://example.com/quiz/12345/take"} ]
media	no	array	An array of media objects. Media object format and rules are identical to those described on the Facebook Developer page on Attachments.
properties	no	object	An object with attributes describing properties of the update. An attribute value can be a string or an object with two attributes, text and href. Example: properties: { "Time": "05:00", "Location": { "text": "Portland", "href": "http://en.wikipedia.org/wiki/Portland,_Oregon" } }

activity - Complete example "activity" value

JSON

  {
  "user_generated_content": "I thought you would appreciate my review.",
  "title": "A Critique of Atomic Pizza",
  "action_links": [
    {
      "href": "http:\/\/example.com\/review\/write",
      "text": "Write a review"
    }
  ],
  "action": "wrote a review of Atomic Pizza",
  "url": "http:\/\/example.com\/reviews\/12345\/",
  "media": [
    {
      "href": "http:\/\/bit.ly\/3fkBwe",
      "src": "http:\/\/bit.ly\/1nmIX9",
      "type": "image"
    }
  ],
  "description": "Atomic Pizza has a great atmosphere and great prices.",
  "properties": {
    "Location": {
      "href": "http:\/\/bit.ly\/3fkBwe",
      "text": "North Portland"
    },
    "Rating": "5 Stars"
  }
}
  

analytics_access

Get statistics for your application in a zip file. Goes great with cron jobs. The process consists of two API calls. The first call is to establish a one time use token to access the analytics server. The second is to use that token to receive a .zip file containing your statistics.

API URL
https://rpxnow.com/api/v2/analytics_access
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key
start	yes	A date formatted to MM/DD/YYYY
end	yes	A date formatted to MM/DD/YYYY

analytics_access - Response

The first call returns a URL to access the analytics file

Parameter	Description
URL	Do a GET with this URL to receive the analytics file

JSON

{
  "url": "http:\/\/rpxnow.com\/export?access_token=19e936b707e7862269c...&end=02\/10\/2010&api=true"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'/>

The report will list total, unique, new, and returning sign-ins per day.

If your application runs on more than one domain the download will include a report for each domain that has data for the given date range, plus a report with totals for all of your domains.

set_auth_providers

Set the providers that will be displayed in the sign-In Interface.

set_auth_providers - Request

API URL
https://rpxnow.com/api/v2/set_auth_providers
Parameter	Required?	Description
apiKey	yes	Your Janrain Engage API key
providers	yes	A comma separated string of provider names.

set_auth_providers - Response

This method has no specific response - It returns an empty success response if it completes without error.

JSON

{
  "stat": "ok"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'/>

Currently supported provider names are:

• aol
• facebook
• google
• live_id
• myspace
• openid
• yahoo
• flickr
• livejournal
• myopenid
• verisign
• wordpress
• blogger
• hyves
• netlog
• twitter
• linkedin
• paypal
• salesforce
• orkut
• vzn
• foursquare

Otherwise, you will be given an error response indicating what was wrong.

providers

Get a list of configured signin and social providers. Note that this API call does not use apiKey to identify the application, but rather, must be called on the application's domain. In this example, results would be returned for the 'my_app' application.

providers - Request

API URL

https://my_app.rpxnow.com/api/v2/providers

providers - Response

Returns configured providers or error.

Parameter	Description
signin	A list of configured signin provider names for the application.
social	A list of configured social provider names for the application.

JSON

{
  "social": [
    "aol",
    "facebook",
    "google"
  ],
  "signin": [
    "aol",
    "facebook",
    "twitter"
  ],
  "stat": "ok"
}

XML

<?xml version='1.0' encoding='UTF-8'?>
<rsp stat='ok'>
  <signin>
    <provider>
      aol
    </provider>
    <provider>
      facebook
    </provider>
    <provider>
      twitter
    </provider>
  </signin>
  <social>
    <provider>
      aol
    </provider>
    <provider>
      facebook
    </provider>
    <provider>
      google
    </provider>
  </social>
</rsp>