Connect.registerUsers

From Facebook Developer Wiki

Revision as of 08:29, 9 July 2009 by Erik Karulf (Talk | contribs)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search

Contents

Description

This method is used to create an association between an existing user account on your site and that user's Facebook account, provided the user has not connected accounts before.

This method takes an array of account data, including a required email_hash and optional account data. For each connected account, if the user exists, the information is added to the set of the user's connected accounts. If the user has already authorized the site, the connected account is added in the confirmed state. If the user has not yet authorized the site, the connected account is added in the pending state.

If the user deactivates their external user account, then call connect.unregisterUsers. To get the number of friends a user has in the pending state, use connect.getUnconnectedFriendsCount.

Parameters

RequiredNameTypeDescription
required api_key string The application key associated with the calling application. If you specify the API key in your client, you don't need to pass it with every call.
sig string An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application. Facebook computes the signature for you automatically.
v float This must be set to 1.0 to use this version of the API. If you specify the version in your client, you don't need to pass it with every call.
accounts array An array of up to 1,000 arrays, or "maps," where each map represent a connected account. Each map can have the following properties:
  • email_hash: The public email hash of remote account. This property is required. Compute the email_hash property as follows:
  1. Normalize the email address. Trim leading and trailing whitespace, and convert all characters to lowercase.
  2. Compute the CRC32 value for the normalized email address and use the unsigned integer representation of this value. (Note that some implementations return signed integers, in which case you will need to convert that result to an unsigned integer.)
  3. Compute the MD5 value for the normalized email address and use the hex representation of this value (using lowercase for A through F).
  4. Combine these two value with an underscore.
    For example, the address mary@example.com converts to 4228600737_c96da02bba97aedfd26136e980ae3761.
  • account_id: The user's account ID on the Facebook Connect site. This property is optional. If you specify the account_id property, then you must also set a Connect Preview URL in your application's settings in order to generate a full user URL. The Connect Preview URL contains an account_id parameter, such as http://www.example.com/profile.php?user=account_id.
  • account_url: The URL to the user's account on the Facebook Connect site. This property is optional. If you specify the account_url property, that URL will be used directly.
Facebook recommends that you specify at least one of either the account_id or the account_url properties.
optional format string The desired response format, which can be either XML or JSON. (Default value is XML.)

Response

This method returns an array of email hashes that have been successfully registered. If any email hashes are missing, we recommend that you try registering them again later.

Notes

  • Registering accounts is idempotent (that is, performing the operation multiple times achieves the same result - it's not a toggle). If the user connects the two accounts, re-registering the account preserves that value.
  • The typical use case for this method will be a bulk transfer of existing users with periodic updates for new users. We recommend that you transfer as many accounts as possible (up to the maximum of 1,000) in a single call for performance reasons.
  • This method is typically used in conjunction with either users.getInfo or fql.query in order to associate external user accounts with Facebook user accounts. Once an email hash has been registered and confirmed by the user (which occurs when the user authorizes the site by logging into it or accepting a Connect request), it will be returned as part of the email_hashes property available via users.getInfo and fql.query.
Retrieved from "http://wiki.developers.facebook.com/index.php/Connect.registerUsers"
reference