SuperRewards - Social 2 Web Documentation

Social 2 Web

« Developer Documentation Index

Social 2 Web API

1. Prerequisites
2. Publisher-side Configuration
3. Social 2 Web Setup
4. Graphics Dimensions and Type
5. XML Feed
6. Facebook Session Key /Access Token
7. Iframe Resizing
8. Showing the Offer Wall and passing custom parameters
9. User Achievements
10. Portal Compliance
11. Additional Help

1. Prerequisites:

An iFrame Facebook application, not FBML. FBML is not supported. Facebook has deprecated FBML so you will need to convert to an iFrame application regardless (Future viral features from Facebook will not be available to FBML publishers. Additionally, iFrame applications are faster for users. [Source]).
Your Facebook application ID
A domain name:
1. 1a. Register a domain name for your application (like yourdomainname.com)
2. 1b. Recommended option: use a subdomain of your domain that you already have (like play.mygreatgame.com)
3. 2. Or, we can host the game on our domain (on a path like apps.superrewards.com/thefarminggame)
The iFrame URL used for your application on Facebook (the canvas URL from the Facebook integration tab of your FB app settings)
You must also understand how our payment and offerwall system works, and how to receive postback notifications from us when a user completes an offer or payment. Please review the publisher documentation here for details.

2. Publisher-side configuration:

On your Facebook app settings (http://www.facebook.com/developers/editapp.php?app_id=XXXXXXX): set the Site URL and Site Domain on the "Web Site" tab to yourdomainname.com or apps.superrewards.com. This will not affect your live application on apps.facebook.com; it will continue working. This simply specifies the domain name allowed to make FB Connect calls outside of facebook.com to log in your users.
Place this authentication script on your server (remove the .txt extension). This script will be used to validate the FB Connect login cookie and return the fb_sig parameters you receive from Facebook on your iFrame URL. You are not allowed to provide us with your FB app Secret Key per the FB Terms of Service, so this script will perform the user authentication validation step on your server. Plug in your FB Secret key and other variables required at the top of the script.
If you have registered your own domain name where you'd like to run your application then set up a CNAME to point to: platform.superrewards.com. Detailed instructions for setting up a CNAME can be found here. Inform your Super Rewards Account Manager when you have completed this step (including the domain you have chosen) so they can enable and set up your custom domain.

3. Social 2 Web Setup:

Contact your Super Rewards Account Manager to have your Social 2 Web enabled on your srpoints.com account. Then you will be able to navigate to the new Social 2 Web tab on your app's Edit page. This section describes the configuration steps available on that page.

Site information
- Facebook App ID: This is the application ID that facebook assigns your application. You can obtain this information by going to the developer application on facebook and clicking on your application.
- Iframe URL: The full URL to your application. This is the same as the Canvas URL on your FB app settings page "Facebook Integration" tab (http://www.facebook.com/developers/editapp.php?app_id=XXXXXX).
- Fan page URL: This can have a couple options depending on how the fan page is set up. If you have a facebook vanity URL then you can enter /YOUR_VANITY_URL or if you just have an app id you can enter the number with no beginning slashes or trailing slashes.
- Validation Callback URL: This is the full URL to the authentication script you placed on your server.
- Email Message: the Social 2 Web has an email invitation feature. You can customize the default message placed at the top of the user's invitation emails.
- Email BG Color: To add some customization to the email importer, this will allow you to pick which color works best for the background of the email importer modal dialog.
- Favicon URL: The URL to the tiny icon that will appear at the top of web browsers. Needs to be formatted image in the ico format
LIVE Social 2 Web URL
- Active: This makes your Social 2 Web active for this app. If it is set active then users can get to it to play your game. If the active checkbox is not set to active then normal users cannot access your game's Social 2 Web.
- Social 2 Web URL: The URL to access your game's Social 2 Web. If active is not checked then the URL will have additional parameters for you to access your game and check how it looks before it goes live.
Facebook Application Permissions Request
- These are the permissions your application will request access to from users. Example, if you check "publish_feed" then a dialog will appear when a user installs your game to allow your application to access their feed and publish items to it. Check only the ones your application needs. The more your application requires the less likely users will grant permission for your application to work correctly.
Customize Your Game's Social 2 Web
- Splash: The main logo users will see when they first come to your game's Social 2 Web. This will be centered on the initial game's Social 2 Web page.
- BG Color: THe background color behind the splash image that will fill out the space behind the game's logo.
- BG Image Choice: This is the wrapper around your game's Social 2 Web. It is on the sides of the main page. You have 6 different color options to choose from. Pick the one that makes your game's Social 2 Web look appealing.
- Tab Color Choice: These are the tabs for the game feed, friends feed and user feeds. You have 6 different color options to use for your game's Social 2 Web.
- Banner: This is your game logo that appears on the page on the upper left. It's a bit off center and hangs over the side a little bit. The image dimensions should be 250 x 100 pixels. Also, having the image's background color be transparent makes the game's Social 2 Web look nicer.
- BG Color: This is the background color for the banner image. If you decide to use this it will make the banner image have the background color you specify.
- Top Bar: This is the bar that runs along the top of the page. Dimensions should be 1116 x 102 pixels.
- BG Color: This is the background color of the top bar image. If you choose to have a color behind it, your selection will be used as the background color.
- Left sprite: This is a background image used for the left column of the game's Social 2 Web. You can optionally have it repeat on the x and y axis.
- BG Color: Set this if you want the left column to have a background color.
- Right sprite: This is a background image used for the right column of the game's Social 2 Web. You can optionally have it repeat on the x and y axis.
- BG Color: Set this if you want the right column to have a background color.
Like Box
- Like Box URL: The fully qualified URL to your Facebook Like Box. Sometimes this is the same as the fan page URL, but usually has "http://www.facebook.com/pages/" before it.
Options
- Cubics Offers On: Talk to your account manager for this feature.
- Skyscraper Offers On: Talk to your account manager for this features.
- XML Item Feed: This is an optional feed you can provide us which allows you to promote anything you like on the left side of the application's iframe. The feed is a standard xml formatted feed and contains two pieces of information. The first piece of information is a click URL. This will be the URL a user will be directed to that was specified for a particular XML feed item. The second piece of information is an image URL. This will be the image that is displayed to the user of a particular item they may purchase or something that you want to advertise to the game users.
- Promobar On: The Super Rewards Promo Bar is an install-exchange where you earn both revenue for paid app-install ads, as well as credits which are used to send new users to your app from peer apps. You can find out more information here.
- Offer button Image: This is in the upper part of the right hand column. This image is used to toggle the user's game screen to the Super Rewards offerwall screen.

4. Graphics Dimensions and Type

Splash Image - This is the main logo when user comes to the game's Social 2 Web and they are not yet logged in through facebook connect. Ideal dimensions are 500 x 500 to 700 x 700 or any deviation of these that look good. The default color of the background is white so ideally the image you create will have a transparent background and would be in a png format.
Banner - This is the logo that appears on the upper right hand side of the game's Social 2 Web main page. It hangs over the edge to create a visually nice effect. If you do not like the hang over you can just create your image with more left side margin or padding and it will offset the logo so it does not hang over the side. The ideal dimensions are 250 x 100 pixels. Anything over will cause layout issues and anything under will be underwhelming for users. Since this will be over your top bar the background for this image should be transparent and preferably in a png format.
Top Bar - this is the image that will run along the entire top of the page. This image should be exactly 1116 x 102 pixels.
Left Sprite - this image can vary in sizes and dimensions. You can have one image that covers up a section of the left hand column or have a single pixel width or height repeated across the x and y axis as your background.
Right Sprite - this image can vary in sizes and dimensions. You can have one image that covers up a section of the right hand column or have a single pixel width or height repeated across the x and y axis as your background.

5. XML Feed

The XML feed is a way for you to add in your own custom items to the game's Social 2 Web. These items could be something in game for users to buy or just letting users know a special promotion is going on. It's all up to you! The xml feed should be structured as follows:
```
<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item>
    <id>000001</id>
    <click_url>#</click_url>
    <img_url>image1</img_url>
  </item>
  <item>
    <id>000002</id>
    <click_url>#</click_url>
    <img_url>image2</img_url>
  </item>
  <item>
    <id>000003</id>
    <click_url>#</click_url>
    <img_url>image3</img_url>
  </item>
</items>
```
There are 3 main fields for each xml item entry. The first is an id that uniquely identifies this item. The second is a URL we will send users to get this item or a link you would like the user to go to. The third field is the image of the item or information you want to convey. Currently we are using an image but eventually we will move to just text so we can go global and use localization. For now an image is the way to communicate with the user. The size of this image must not go beyond 164 pixels in width. If it does it will disrupt the column size and it will look ugly. Obey the width :-)

Additional XML Options
Modal Popup
This option will cause a modal popup with the iframe's source being the click url that is passed in the xml. The height and width must be specified if not it will not be displayed. The key tags, beyond the three perviously discussed, for the modal popup xml are modal_popup, modal_height, and modal_width.
```
  <item>
    <id>000003</id>
    <modal_popup>1</modal_popup>
    <modal_height>650</modal_height>
    <modal_width>730</modal_width>
    <click_url>#</click_url>
    <img_url>IMG</img_url>
  </item>
```
Iframe Redirect
When the tag iframe_redirect is set to 1, when someone clicks on this item it will take the click URL and replace the game iframe's source with that URL.
```
  <item>
    <id>000001</id>
    <iframe_redirect>1</iframe_redirect>
    <click_url>#</click_url>
    <img_url>IMG</img_url>
  </item>
```

6. Facebook Session Key /Access Token

If your game uses the facebook parameter "fb_sig_session_key" we pass a parameter called "access_token" to your iframe that you can use instead of the "fb_sig_session_key". The access token is what comes out of the facebook connect call. Facebook connect is moving to the use of this access token instead of the fb_sig_session_key.

7. Iframe Resizing

For iframe dynamic resizing you need to add this script to each of the application pages header. You just need to include this script file and Do not need to download the file and host it. Just include this tag.

  <script type="text/javascript" src="http://cdn.superrewards.com/js/game_platform.js?v=110727"></script>

This script will bring in a function called "resizeGamePlatform" -- You should probably make a javascript function in your canvas page* that wraps the call to this function, like this:


    // Call this function whenever you want to set the iframe height.
    function myResizeMethod(height) {
      resizeGamePlatform(height, "http://www.examplegame.com/"); //Must match your game's domain exactly
    }

To resize automatically on page loads, add something like this:

If you use jQuery:


    jQuery(document).ready(function() {
      var gameheight = jQuery(document).height();
      myResizeMethod(gameheight);
    })

* Make sure to only add this code to your page when it is running on Social2Web. You can detect the argument "platform=1" in the URL—you'll always get that parameter when you're running via Social2Web.

*NOTE* The only way this script works is if the game's Social 2 Web domain (that is, the URL that shows in the browser when the user is playing your game) and the domain you pass to the resizeGamePlatform() method match exactly. This also means that the sub-domains have to match exactly. This is to adhere to the Same Origin Policy. For more information about this policy read more here

8. Displaying the Offer Wall and passing Custom Parameters to it

First make sure you are including our javascript library which also provides iframe resizing (see above).

    <script type="text/javascript" src="http://cdn.superrewards.com/js/game_platform.js?v=110727"></script>

This gives you several features related to the offer wall. First, define your own methods to wrap our API calls while providing your Social 2 Web game URL. For example:


    //Define your own methods:
    
    function myShowOfferWall(customParams) {
      showS2WOfferWall(customParams, "http://www.examplegame.com/"); //Must match your Social 2 Web game URL exactly
    }
    
    function mySetCustomParams(customParams) {
      setS2WCustomParams(customParams, "http://www.examplegame.com/");
    }

NOTE: THE FOLLOWING EXAMPLES assume you have already created your wrapper functions as shown above. You may of course name your wrapper functions anything you want.

Just Displaying the offer wall.


    //Just show the offer wall
    myShowOfferWall("");

Displaying the offer wall with custom parameters. IMPORTANT NOTE: ALL CUSTOM PARAMETERS MUST START WITH custom_!!


    //show the offer wall with custom parameters
    //NOTE: ALL CUSTOM PARAMETERS MUST START WITH custom_ !!
    myShowOfferWall("custom_blah=123&custom_foo=bar");

Just set custom parameters for any future offerwall visits the user might make on this pageview.


    //Just set the parameters "blah" and "foo"
    mySetCustomParams("custom_blah=456&custom_foo=blah");

9. User Achievements

User Achievements are a way to drive users back to the site in a fun and competitive manner. Much like games where people compare their in-game items with friends, this provides another fun way for users to be rewarded by playing on the Social 2 Web. Some of the basic achievements users can achieve are premier user, and X number of days in a row they have come to your Social 2 Web. More achievements will be added soon and an API where games can add their own custom achievements.

10. Portal Compliance

Wild Tangent Portal Compliance Requirements.

1. Your app cannot have any Direct Pay integrations like PayPal, GoogleCheckout and so on.

2. If you have an in-app offerwall, the offerwall needs to include a Super Rewards click source that will be passed to your app's iframe. The parameter is cs. Wild Tangent also has partner ID's that are passed to your app's iframe. It also needs to be based to any Super Reward's direct payment option and the Super Rewards offerwall. The parameter that is passed is custom_ptrefid.

3. Your app cannot include/display Facebook Credits on any portal site. (Facebook credits on Facebook is still okay). Your app also cannot include any Facebook credit assets in the game.

4. No app exchange tool bars (cross-promotion game bars for advertising other apps).

5. App posts/achievements made on a portal that post to Facebook must link back to your game's URL on Wild Tangent. Instructions for doing this will be provided after the game has passed Wild Tangent's QA evaluation of your app.

6. In order to promote your app across their network, you must provide marketing assets to Wild Tangent. The requirements for Wild Tangent marketing assets can be found here: https://developer.wildtangent.com/Publish/MarketingAssets.

7. Time-outs and reloads of your app need to check if a portal id passed, and if so, the reload/refresh should go to the appropriate place.

8. If your app's frame changes size or you have portions of your app that change from the normal height you have specified in the Social2Web setup on http://www.srpoints.com you must implement the iframe resizing code. Instructions on what to include can be found here. http://srpoints.com/docs/Social2Web_Integration.html#Iframe_Resizing:

11. Additional Help

Contact your Super Rewards Account Manager for help. We can walk you through the process or answer any questions you may have.

Table Of Contents

Social 2 Web API

1. Prerequisites:

2. Publisher-side configuration:

3. Social 2 Web Setup:

Site information

LIVE Social 2 Web URL

Facebook Application Permissions Request

Customize Your Game's Social 2 Web

Like Box

Options