Skip to main content

LifeCycleEvent

Outline​

Life Cycle Event is a mechanism that notifies the partner server when certain events occur in relation to an application. The following events are currently available:

EventExplanation
addappUser has installed the application.
removeappUser has uninstalled the application.
joingroupUser has joined the game’s official group.
leavegroupUser has left the game’s official group.
postdiaryUser has posted a diary entry about the game.

Implementing Life Cycle Events​

Adding a description to the Gadget XML file.​

Describe the settings of the partner server that will receive event notifications.

AttributeValue
relThe life cycle event type (event.addapp
hrefThe URL to receive notifications at the partner server = endpoint URL
methodType of request made to the endpoint URL (GET
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Sample Application">
<Link rel="event.addapp" href="http://www.example.com/addapp" method="POST" />
<Link rel="event.removeapp" href="http://www.example.com/removeapp" method="GET" />
<Link rel="event.joingroup" href="http://www.example.com/joingroup" method="GET" />
<Link rel="event.leavegroup" href="http://www.example.com/leavegroup" method="GET" />
<Link rel="event.postdiary" href="http://www.example.com/postdiary" method="GET" />
</ModulePrefs>
<Content view="mobile" type="url" href="http://www.example.com/index.html" />
</Module>

Notification requests​

Request type​

addapp​

An event which occurs when an application is installed.

Parameter nameExplanation
eventtypeThe type of event (event.addapp)
opensocial_app_idApplication ID
idUser ID of the user who installed the application
mbga_invite_fromUser ID of the user who sent the invitation
removeapp​
  • An event which occurs when an application is uninstalled.

    Parameter nameExplanation
    eventtypeType of event (event.removeapp)
    opensocial_app_idApplication ID
    idUser ID of the user who has uninstalled the application
joingroup​
  • An event which occurs when a user joins a game’s official group.

    Parameter nameExplanation
    eventtypeType of event "event.joingroup"
    opensocial_app_idApplication ID
    idUser ID of the user who has joined the game’s official group
leavegroup​
  • An event which occurs when a user leaves a game’s official group.

    Parameter nameExplanation
    eventtypeType of event "event.leavegroup"
    opensocial_app_idApplication ID
    idUser ID of the user who has left the game’s official group
postdiary​
  • An event which occurs when a user posts a diary entry about a game.

    Parameter nameExplanation
    eventtypeType of event "event.postdiary"
    opensocial_app_idApplication ID
    mbga_diary_idDiaryID
    idUser ID of the user who has posted a diary entry about the game

Request format​

  • When id:102 is invited by id:101 and then installs Application A.

    http://www.example.com/addapp?opensocial_app_id=A&eventtype=event.addapp&id=102&mbga_invite_from=101
  • When id:101, id:102, and id:103 install Application A, and the notifications are issued simultaneously.

    http://www.example.com/addapp?opensocial_app_id=A&eventtype=event.addapp&id=101&id=102&id=103
  • When id:101 and id:102 join the official group of Application A.

    http://www.example.com/joingroup?opensocial_app_id=A&eventtype=event.joingroup&id=101&id=102
  • When id:101 posts a diary entry about Application A.

    http://www.example.com/postdiary?opensocial_app_id=A&eventtype=event.postdiary&id=101&mbga_diary_id=10001

A signature by OAuth is applied to requests. Make sure to confirm the validity of the Authorization request header.

Response​

Status: 200
Content-Type: text/plain

OK

When a response other than the above is returned, it is regarded as an error and then re-sent at the time of the next notification. It is also regarded as an error if the response takes 10 seconds or more from the time the request is issued. If a certain number of notification errors is reached, the notification is destroyed.

Notification frequency​

Event notifications to an endpoint are not carried out on a real time basis from user actions, but are issued with a time lag. Notifications usually arrive in a few minutes in both the production and Sandbox environments, but notifications may be delayed due to system load.
Be sure to implement settings such that 200 is returned as the status code indicating successful reception at the endpoint.

Restrictions​

Life Cycle Event currently has the following restrictions.

  • No notifications will be sent for joingroup, leavegroup, and postdiary if the user has not yet installed or has uninstalled an application.

OpenSocial v1.0 Lifecycle Events
OpenSocial v0.9 Lifecycle Events

Change history​

  • 12/03/2012
    • Added information regarding event notification frequency.
  • 07/29/2011
    • Added description of the events joingroup, leavegroup, and postdiary.