Invite Friends and Reward
Next, you will develop a program that uses the Invite friends service to invite a friend and provide an incentive.
Including a Link to the Invite Friends Service
First, develop a screen which will provide a link to the Invite friends service. The following shows the code for invite_friends.php.
As in the previous chapter, this code is divided into PHP and HTML sections. The PHP code uses the RequestValidator class of validator.php to verify the validity of the request from the Gadget server in the same way as shown in the previous chapter.
For the href attribute of the A tag in the HTML, specify the string invite:friends?... When this specification passes through the Gadget server, it is automatically converted to a link to the Invite friends service. In this tutorial, url and image are specified as parameters of the Invite friends service. For url, specify the URI-escaped value of the URL to go to after a friend is invited. The URL to go to here is http://dev.gameserver.com/invite_friends_finish.php. For image, specify the URI-escaped value of the URL of the image that will be displayed within the MiniMail that is sent to the invited user. In this tutorial, http://dev.gameserver.com/img/invite.gif will be used as the URL to display the image.
Providing an Incentive when Sending the Invitation
This section describes how to provide an incentive when the invitation MiniMail is sent. Two methods are available for providing incentives. The first method is to provide the incentive when the invitation is sent. The second is done when the invitation is concluded (acted on by the invitee). This section describes the first method. The second method is described in a later section. Place the following PHP code in the file invite_friends_finish.php in the path specified by the url parameter in the previous section.
In the PHP part of the code, the verification of validity is done just like the code in invite_friends.php.
When the URL of this PHP code is activated, the user IDs of the invited users (separated by commas if there is more than one) are automatically assigned in the invite_member parameter. The number of invited users is entered in $number. You can use the values of $number and $invitees to provide an incentive such as "A user who invited at least YY people will receive a present of XX！" .
Providing an Incentive After the Invitation is Concluded (acted on by the invitee)
This section describes how to use the lifecycle event setting from the previous section to provide an incentive to the "invited" user when the user installs the actual application.
Put the following PHP code in the file lifecycle_event_addapp.php. This PHP code is invoked and called from the platform's server when a lifecycle event occurs.
Although a lifecycle event is not a request from the Gadget server, its validity must still be verified in a similar manner as in previous code.
For an addapp lifecycle event, the user ID of the user sending the invitations is assigned to the request parameter mbga_invite_from. This enables the application to provide this user with an item from the game to use as a reward. Note that although the addapp lifecycle event also occurs when the application is installed and not just through an invitation, the request parameter mbga_invite_from is not assigned in this case.
Finally, the string OK is returned along with an HTTP status code of 200.
Registering the Lifecycle Event in gadget.xml
Registering the lifecycle event in gadget.xml enables the event to be detected when the lifecycle event occurs. In this tutorial, you will add a Link tag to gadget.xml and set it so that event.addapp can be detected as shown below. Specify rel, href, and method as parameters. For rel, specify the type of event. The code below shows how to specify event.addapp to detect the event indicating that the invited user has installed the application. For href, specify the endpoint URL for receiving the event notification. Specify the URL http://dev.gameserver.com/lifecycle_event_addapp.php here. For method, specify "GET" and set it so that it will access the target URL.
Since the cache must be cleared if gadget.xml is updated, press the "Refresh" button on the "Common" screen on the Mobage Developer Site, and if the addapp event URL is displayed as follows, the registration is complete.
Creating a Friend of a Test User
Prepare two test users, one for the user sending the invitation (SandboxUser1 below) and one for the invited user (SandboxUser2 below). Since SandboxUser1 was already created, use the same procedure as described in the tutorial here to create another test user named SandboxUser2.
Use the Sandbox support feature to set the two test users to be friends. Access http://sb-sp.mbga.jp/_sandb_top from the browser.
- If you are logged in, logout and then login again as SandboxUser1.
Click "Account List".
When the list of test users is displayed, select SandboxUser2, who is the invitee.
After the profile page opens, select the following link to send a friend request.
Follow the screen transitions to complete the request.
Next, log out of SandboxUser1 and use SandboxUser2 to login to the Sandbox support feature page.
Click "Account List" > "SandboxUser2" to display that user's My Page and select the following link to accept the friend request.
Now SandboxUser1 and SandboxUser2 are friends.
Verifying Operation on an Actual Device
Place the following PHP programs that you developed on the game server.
- invite_friends.php
- invite_friends_finish.php
- lifecycle_event_addapp.php
Also, add a link to invite_friends.php in the index.html and then replace index.html.
Re-launch the client application that you installed on the actual device in the previous chapter. While the application is starting up, press the Home button at the top to update the start page. Now that the Invite Friends to This Game link has been added as shown below, you can click on the link and go to invite_friends.php.
Tap Click to Invite Friends to go to the target for the service tag.
The Invite friends screen should appear so you can invite SandboxUser2 directly.
If the invitation is successful, the screen will switch to the invitation completion screen. Tap the link at the bottom to return to the game.
invite_friends_finish.php, which was specified as the return destination, will be displayed and the invitation process will be completed.
At this point, since the path would end up getting interrupted in the Sandbox environment, install the Sandbox application on another mobile device, log in as SandboxUser2, who is the invited user, and conclude the invitation (take the relevant action). When the new user installs the application, the lifecycle event is reported.
Verify in the log that lifecycle_event_addapp.php was requested and the user ID of SandboxUser1, who is the user who sent the invitation, is assigned in the request parameter mbga_invite_from.
This completes the tutorial for inviting Mobatomo (Friend) and providing an incentive.
Reference Material
For more information about the Invite friends service, please see here.
For more information about Gadget XML lifecycle event definitions, please see here.
For more information about lifecycle event notification requests, please see here.
Revision History
- 12/11/2012
- Initial release