OpenSocial RequiredFields

From VZ Developer Wiki
Revision as of 16:26, 7 March 2011 by Seba (talk | contribs)
Jump to: navigation, search

General Guidelines | XML Specification | Features | Views | JavaScript API | REST API | Tutorials | OAuth


OpenSocial Required Fields

If your gadget is taking advantage of OpenSocial functionalities and is therefore declared as a social gadget with 'opensocial-x.x' as required:

 <Require feature="opensocial-0.9"/>

you might consider restricting the vCard fields your gadget is requesting from the user's personal data. The available field names are

  • gender
    • will return the user's gender
  • birthday
    • will return the user's birthday date
  • emails
    • will return only return the user's main e-mail address
  • addresses (includes all childs of addresses)
    • will only return one postal address
  • locality (also included in adresses)
    • will return the city where the user resides
  • country (also included in addresses)
    • will return the country where the user resides
  • phoneNumbers
    • will only return the user's main phone number
  • thumbnailUrl (includes photos)
    • will provide the url to the user's profile picture
  • photos
    • will provide the same content as 'photos', can change in future

Applied in a gadget.xml snipplet, requesting the fields gender, emails, and the thumbnail URL will look as follows

 <Require feature="opensocial-0.8">
        <RequiredFields>
                <Field>gender</Field>
                <Field>emails</Field>
                <Field>thumbnailUrl</Field>
        </RequiredFields>
</Require>

The following fields will be available right away since they are within the implicit minimal field requirements

  • id
  • name (includes displayName and all childs of name)
  • profileUrl
  • published
  • updated
  • platform

However, including one or more of these fields within the 'RequiredFields' section will enhance the user experience by not showing unused information during the gadget installation process. Conclusion: Always specify your field requirements!

If you want to request additional data from your users later on you can either do this by uploading a new revision, all your users will get a short migration screen once they launch your gadget next, or you can request more data selectively by using the vz.vcard.update method in your gadget's JavaScript.

Help.png

This tutorial will give you more examples or information on these features:
Lesson 16: Request additional data from your user

What's in for me?

Specifying your field requirements upfront has the following advantages

  • Higher conversion rate
    • During installation only the requested fields will be shown. The less fields he/she is asked to fill out, the more likely he/she will install your gadget as opposed to leave the installation process because of being overwhelmed by too many questions.
  • You can ask for more at any time
    • If your business logic changes or you want to ask the user's permission for other fields any time later, you can simply request those fields in future. The user will only be asked to fill out the field(s) you ask for as complementary data to the already existing information.
  • Enhanced transparency for your users.

Please Consider

  • Providing required field information is not mandatory yet but may become mandatory in future
  • The example described above will only work within a <Require feature="opensocial-x.x" /> section
  • The former RequiredDate attribute within the ModulePrefs section is now deprecated