Weiter zu Netlog

noch Sekunden

Developer / Documentation / Netlog OpenSocial Credits Extension

The Netlog user base is used to working with credits which they can earn or buy on our site. These credits correspond with real monetary value, and can be used to access various 'premium' features: virtual goods, putting a picture in the spotlight, etc...

With our permission, apps can both request credits from, or give them to, the user of the app. This happens trough our credits API which is the subject of this article: requesting credits and giving credits.

This article requires you are familiar with OpenSocial.

Requesting credits from the user

Preparation: callback script and credits key

Before you can work with our credits API, you have to provide us the URL to your payment callback script (see below), for example: http://www.mysite.com/verifypayment.php.

Once we know your callback script location we provide you with a Credits Key, which is needed to send/receive calls with the credits API.

1. initiating the transaction within the gadget

First, require the (Netlog-specific) feature payment at in the section of your openSocial gadget:

<Require feature="payment"/>

To request credits from the viewer, create a Payment object and use the functionPayment.requestPayment() as in the example below:

<input type="button" id="credits" value="Send" onclick="upgrade()"/>
<div id="result"></div>
<script>
function upgrade()
{
 var payment = new Payment(20, 'Sending a christmas tree will cost you 20 credits');
 var opt_params = {};
 Payment.requestPayment(payment, handlePayment, opt_params};
}
function handlePayment(response)
{
 //handle returned responseitem (see step 3)
}
</script>

When requesting credits the user will be prompted with a dialog to confirm the transaction. Should the user not have enough credits, he will be able also purchase them right within this dialog. This is how it looks:

payment screenshot

2. Payment callback script on your server

When the user accepts or denies the payment, the payment information is sent to your payment callback script (the location of which you need to give us) through a signed makeRequest call.
This way, you can verify the payment on your backend securely.
The data is sent using HTTP POST and contains following fields:

  • userid - the userid of the user who accepted or denied the payment.
  • amount - amount of credits for this payment.
  • action - whether the user has accepted or denied the payment. Possible values are ACCEPT and DENIED.
  • token - unique token for this payment.
  • secret - simple verification that this call really came from us: md5(token, userid, amount, action, creditsKey)

When processed, your payment callback page should return a HTTP 200 OK status code with the following body: md5(concat(token, creditsKey));

The payment will only be done when your server sends back this answer correctly. Otherwise the payment will not occur and result in an error. This is a simple example of a callback script in php:

 <?php
 //Verify the signed request first
 $creditsKey = 'some_key';
 echo md5($_POST['token'] . $creditsKey);
 ?>

3. Handle the payment on the client side

Once your server has responded in a correct way, an error occured, or when the user cancelled the request, your callback function will be called - this is the second argument you passed on to Payment.requestPayment() in step 1.
This function should accept one parameter, which is an opensocial.ResponseItem.
If no errors occured, the data in this ResponseItem is a Payment.

function handlePayment(response)
{
 if (data.hadError())
 {
 document.getElementById('result').innerHTML = 'Error: ' + response.getErrorMessage();
 }
 else
 {
 var state = data.getField('state');
 if (state == Payment.State.ACCEPTED)
 {
 document.getElementById('result').innerHTML = 'Credits received';
 }
 elseif (state == Payment.State.DENIED)
 {
 document.getElementById('result').innerHTML = 'Credits not received';
 }
 elseif (state == Payment.State.CANCELLED)
 {
 document.getElementById('result').innerHTML = 'Cancelled by user';
 }
 }
}

One final note: make sure you thorougly test all the user scenario's, e.g. the user canceling the transaction, something going wrong with your server connection...

Giving credits to the user

To be able to this you need a Credits Key provided by us.

Contrary to the requesting of credits, giving them happens trough OpenSocial REST. This means the giving of credits does not require the user to be visiting Netlog at that specific moment.

Giving credits to the user happens in two subsequent POST calls to our API. The first call requests a token, the second call sends this token back to our API to confirm the transaction.

1. call to request security token

POST to http://api.netlog.com/go/api/action=getCreditsToken with the following parameters:
  • amount - how many credits to give the user
  • appid - your app id (to be provided by us
  • userid - you can fetch this with our openSocial REST API for example
  • sig - hash of the previous parameters as follows: md5(concat(amount,appid,userid,creditskey)
This call will return JSON:
  • On failure: {'success":false, "error": "some error"}
  • On success: {'success":true, "token": "anMD5hash"}

2. Call to specify the actual transfer

POST to http://api.netlog.com/go/api/action=giveCredits with the following parameters:
  • appid - your app id (to be provided by us
  • token - received as response to the first POST call.
  • sig - hash of the previous parameters as followsmd5(concat(appid,token,creditskey))
This call will return JSON:
  • On failure: {'success":false, "error": "some error"}
  • On success: {'success":true}

Note that the vast majority of apps will not be allowed to give credits to our user - this right is granted only after careful discussion. Also, we may only allow your app to give out a limited amount of credits in total.

Read more...