Table of Contents

Let the methods begin

addView:

Parameters:

callback: String

animated: bool

url: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information
  • animated: Whether there should be an animation when adding the view.

Notes:

This view will be presented by pushing another view onto the stack, animating from the left to right.

This method cannot be called in onBridgeReady, and must be called at least 1 second after the VApp has been launched.

Adding a view will engage the chrome navigation (top left button on iOS and hardware back on Android) such that clicking it will remove the view. When all views are cleared the button closes the VAPP. In all other cases the click will close the VAPP.

Invocation:

function addViewCallback(message) { } 

//Add a view to the screen pointing to myurl.com, in an animated fashion 

VAPP.addView(addViewCallback, true, 'http://myurl.com'); 

allowToLeave:

Description:

This function sets a flag which says whether the VApp is allowed to exit without the user being prompted. If it is set to false, the user will see a message that says ‘You have not completed the engagement, are you sure you wish to leave’ when they hit the back button in the top left corner of your VAPP.

NOTE: this feature is only available if there is a point opportunity still available to the user in your APP. If your user has attained the maximum amount of points your app can award in a single session or if no points are assigned, this flag is ignored.

Parameters:

callback: String

enabled: bool

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information
  • enabled: A boolean which denotes whether the user will be prompted upon exiting the app.

Invocation:

function allowToLeaveCallback(message) { } 

//Allow the user to leave without being prompted 

VAPP.allowToLeave(allowToLeaveCallback, true); 

//Don't allow the user to leave without being prompted 

VAPP.allowToLeave(allowToLeaveCallback, false); 

assignPoints:

Description

This function allows the VApp to add points to a user’s Viggle account for completing an event.

Parameters:

callback: String

result: String

info: Object

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information
  • result: A notice to the VApp of whether the event has completed. If so, the user will now be allowed to leave the VApp as per the prompt setting in VAPP.allowToLeave
  • info: An object that can send information along with your reflect request. Often used in the same ways a dictionary would be.

Notes:

A VApp can not send more points in total than the maximum points a VApp has been granted.

Note: By default Viggle grants your VApp the ability to issue one (1) point per session using this call. When your application is certified to run within Viggle, we will work with you to set up larger point grants if appropriate.

result: You can choose either ‘complete’, or ‘incomplete’. It defaults to complete if neither of these parameters is passed in properly.

Invocation:

function endCallback(message) { }

var info = {points:75} 

//Will not allow the user to close the VApp without being prompted 

VAPP.assignPoints(endCallback, 'incomplete', info); 

//Will allow the user to close the VApp without being prompted 

VAPP.assignPoints(endCallback, 'complete', info); 

browserGoBack:

Description

If your VApp is loading multiple pages, or using pagination in any way, this function allows you to go back to the last page that was visited.

Parameters:

callback: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information

Invocation:

function browserGoBackCallback(message) { } 

VAPP.browserGoBack(browserGoBackCallback); 

browserGoForward:

Description

If your VApp is loading multiple pages, or using pagination in any way, this function allows you to go forward to the next page in the navigation stack (assuming the user has come from it).

Parameters:

callback: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information

Notes

An example: If the VApp loads 3 pages, and the user has gone from 1 to 2 to 3, then back to 2, browserGoForward will send him to go to page 3.

Note:

Invocation:

function browserGoForwardCallback(message) { } 

VAPP.browserGoForward(browserGoForwardCallback); 

browserLoadPage:

Description

This function allows your VApp to load a webpage, based on the URL you point this function to.

Parameters:

callback: String
urlToLoad: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information
  • urlToLoad: The URL that your VApp should load.

Notes

This method has no effect on chrome navigation (top left button on iOS and hardware back on Android). Clicking it will exit the VApp.

Invocation:

function browserLoadPageCallback(message) { } 

VAPP.browserLoadPage(browserLoadPageCallback, 'http://iamaurl.co.uk'); 

close:

Description:

This function returns a user back to Viggle, closing the VAPP.

Parameters:

callback: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information

Invocation:

function closeCallback(message) { } 

VAPP.close(closeCallback); 

collapseAd:

Description:

Use this function to collapse an ad displayed with the showAd() function.

Parameters:

html element: DOM element

  • html element: The html element, usually a div, which has been dressed with a Viggle served ad.

Invocation:

 VAPP.collapseAd(document.getElementById('mydiv'));

displayAdCompletedCheckmark:

Description:

Use this function to display a check mark by an ad displayed by the showAd() function. This is intended to indicate that the user has clicked on the ad.

Parameters:

html element: DOM element

  • html element: The html element, usually a div, which has been dressed with a Viggle served ad.

Invocation:

 VAPP.displayAdCompletedCheckmark(document.getElementById('mydiv'));

enableChrome:

Description:

This function denotes whether a VApp should show back and forward buttons, allowing a user to page through their browsing history. Set to on (true) by default.

Parameters:

callback: String

animated: bool

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information
  • enabled: Whether there should see a back and forward button.

Invocation:

function enableChromeCallback(message) { } 

//Show the bars 

VAPP.enableChrome(enableChromeCallback, true); 

//Hide the bars 

VAPP.enableChrome(enableChromeCallback, false); 

getAllowToLeave:

Description

This function returns the value of allowToLeave, which denotes whether the user is allowed to leave the VApp without being prompted.

Parameters:

callback: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information

Invocation:

function getAllowToLeaveCallback(message) { } 

VAPP.getAllowToLeave(allowToLeaveCallback); 

getCurrentShow:

Description:

This function returns information about the show from whose showpage the user opened your VAPP.

Parameters:

callback: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing the response to your query. In this case it contains information about the show from whose showpage the user opened your application

Invocation:

function getCurrentShow(message) { } 

VAPP.getCurrentShow(getUserInfoCallback); 

getCurrentShowCheckinOffset:

Description:

If the user is checked into the show from whose showpage your VApp was accessed, the message in this method’s call back will contain the number of seconds into the current show the user checked in. If the user has not checked into the current show, the value will be 0.

Parameters:

callback: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing the response to your query. In this case it contains information about the show from whose showpage the user opened your application

Notes

A non zero value will only be populated by an audio checkin. Manual checkins will register a 0.

Invocation:

function getCurrentShowCheckinOffset(message) { } 

VAPP.getCurrentShowCheckinOffset(getCurrentShowCheckinOffsetCallback); 

getLike:

Description:

Use this function to determine if a given show is liked by the current user.

Parameters:

callback: String

showID: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing the response to your query.
  • showID: The TMS ID of the show whose Like status you’re checking

Notes:

You must know what the TMS ID for a show is, for this function to be useful to you. For the show the user clicked to arrive at your VApp, use VAPP.getShowInfo().

Invocation:

function getLikeCallback(message) { } 

VAPP.getLike(getLikeCallback, 'SH005927330000'); 

getReminder:

Description

This function returns whether a reminder is set for the show that is passed in as episodeID.

Parameters:

callback: String

episodeID: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing the response to your query.
  • episodeID: The TMS ID of the show you are setting a reminder for.

Notes:

You must know what the TMS ID for a show is, for this function to be useful to you. For the show the user clicked to arrive at your VApp, use VAPP.getShowInfo().

Invocation:

function getReminderCallback(message) { } 

VAPP.getReminder(getReminderCallback, 'SH005927330000); 

getUserInfo:

Description:

This function returns you Viggle user information, about the person participating in this VAPP.

Parameters:

callback: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing the response to your query. In this case it contains all the user information available to your application

Notes:

When developing your VApp you will see more user information than your app will likely have access to when it goes live. Specifically you should only rely on having the following information:

  • gender
  • displayname
  • GUID
  • zipCode
  • primaryTVProvider (provided as a TMS Headend ID)

Invocation:

function getUserInfoCallback(message) { } 

VAPP.getUserInfo(getUserInfoCallback); 

linkout:

Description:

This function allows the VApp to take a user to an external page.

Parameters:

callback: String

url: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • url: A URL that you would like to point the VApp to, outside the context of Viggle.

Notes:

url: This can be a link out to a webpage, that you open in Mobile Safari, or if you have an application that you would like to go to, it’s custom URL scheme.

Invocation:

function linkoutCallback(message) { } 

//This will open in Mobile Safari 

VAPP.linkout(linkoutCallback, 'http://placekitten.com/400/80'); 

//This will open up your custom app 

VAPP.linkout(linkoutCallback, 'myurlscheme://somefunctionofmyapp'); 

playVideoWithFeedback:

Description:

This function allows the VApp to play a video, while remaining inside the VAPP. Before or after the video, you can add and remove the video, allowing the user interaction.

Parameters:

startcallback: String

buffercallback: String

finishcallback: String

url: String

showLeavingEarlyDialog: bool

closeWholeApp: bool

  • startcallback: A callback for when the video has begun playing. Accepts a JSON parseable string containing diagnostic information
  • buffercallback: A callback for when the video has completed buffering. Accepts a JSON parseable string containing diagnostic information
  • finishcallback: A callback for when the video has finished playing. Accepts a JSON parseable string containing diagnostic information
  • url: The url that points to the video you are attempting to play. Accepts a JSON parseable string containing diagnostic information
  • showLeavingEarlyDialog: A boolean which denotes whether the user will be prompted upon exiting the video.
  • closeWholeApp: A boolean which denotes whether the user will be taken back to the show page upon completion of the video.

Notes:

buffercallback: If you are loading a secondary advertisement alongside your video, this is when your ad will begin to load in the background. The process is transparent to the end user, loading underneath the video.

showLeavingEarlyDialog: If this parameter is set to false, the user will receieve a message that says: ‘You have not completed the engagement, are you sure you wish to leave’ when they hit the back button if they have not yet earned any points.

closeWholeApp: If this parameter is set to true, after the video completes the user will be taken back to where they came to the VApp from, within Viggle. If this parameter is set to false, after the video completes, the user will be taken to the webview that launched the video, where the VApp may continue to interact with the user.

Invocation:

 
function playVideoWithFeedbackVideoStartedCallback(message) { } 

function playVideoWithFeedbackVideoBufferingFinishedCallback(message) { } 

function playVideoWithFeedbackVideoFinishedCallback(message) { }(message) { } 

//The user will be shown a dialog that they are leaving early, and will be taken back to Viggle, to the page which they came from to get to the VAPP. 

VAPP.playVideoWithFeedback(playVideoWithFeedbackVideoStartedCallback,playVideoWithFeedbackVideoBufferingFinishedCallback, playVideoWithFeedbackVideoFinishedCallback, 'http://someurl/somevideo.mp4', true, true); 

//The user will be shown a dialog that they are leaving early, but will stay within the VApp, where they can continue to interact with your VAPP. 

VAPP.playVideoWithFeedback(playVideoWithFeedbackVideoStartedCallback,playVideoWithFeedbackVideoBufferingFinishedCallback, playVideoWithFeedbackVideoFinishedCallback, 'http://someurl/somevideo.mp4', true, false); 

postToSocialNetwork:

Description:

This function allows the VApp to post to a social network. It will bring up a view that allows the user to post to any linked accounts, or add accounts to be linked for posting.

Parameters:

callback: String

defaultMessage: String

subtitle: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • defaultMessage: The message that will be prepopulated for the user when posting to a social network.
  • subtitle: The text that appears underneath which social network you are posting to.

Notes:

The subtitle can be any text, but preferably short, since it is going into a space constrained input field.

This method cannot be called in onBridgeReady, and must be called at least 1 second after the VApp has been launched.

Invocation:

function postToSociaNetworkCallback(message) { } 

VAPP.postToSocialNetwork(postToSociaNetworkCallback, "I'm playing this neat game! #mygame", "My Game's Awesome Title"); 

reflect:

Description:

This function sends a message to your VAPP. It is mostly used for debugging purposes.

Parameters:

callback: String

info: Object

  • callback: A function that can be used for diagnostic purposes.
  • info: An object that can send information along with your reflect request. Often used in the same ways a dictionary would be.

Invocation:


function reflectCallback(message) { } 
VAPP.reflect(reflectCallback, 'Hi there from javascript'); 

removeView:

Parameters:

callback: String

animated: bool

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • animated: Whether there should be an animation when removing the view.

Notes:

This view will be removed from the stack, animating from the right to left. This method will likely be called from a different VApp then the one which spawned the view. The Viggle wrapper will manage the stack order.

Invocation:

function removeViewCallback(message) { } 

VAPP.removeView(removeViewCallback, true); 

setDesiredOrientations:

Description:

This function allows the VApp to denote which orientations it would like to operate in.

Parameters:

callback: String

orientations: Array

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • orientations: The orientations that you would like your VApp to work in.

Notes:

The two orientations that are acceptable are ‘portrait’, and ‘landscape’.

The default orientation is ‘portrait’, so if no orientation is specified, you will not have landscape support.

If you ask for portrait, you will be given portrait, but not portraitUpsideDown.

If you ask for landscape, you will be given landscapeLeft and landscapeRight capabilities. If you ask for a specific orientation, please make sure your VApp looks good and runs well in that orientation.

Invocation:

function setDesiredOrientationsCallback(message) { } 

//Landscape left and landscape right orientations 
VAPP.setDesiredOrientations(setDesiredOrientationsCallback, ['landscape']); 

//Landscape left, landscape right, and portrait orientations 

VAPP.setDesiredOrientations(setDesiredOrientationsCallback, ['landscape', 'portrait']); 

setLeftButtonTitle:

Description:

This function allows the VApp to change the title of the button in the top left corner, which is used for exiting the VAPP.

Parameters:

callback: String

title: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • title: Set the title of the button that appears on the top left of your VAPP.

Notes:

This method is not needed on Android, only iOS. Be sure the handle the exception generated by the Android webview when setting this value is attempted.

This does not change the functionality of the button, just the text that is displayed to the user.

Invocation:


function setLeftButtonTitleCallback(message) { } 

VAPP.setLeftButtonTitle(setLeftButtonTitleCallback, 'Done'); 

setLike:

Description:

This function can set a like if a show is unliked, or unlike if a show is liked.

Parameters:

callback: String

showID: String

shouldLike: bool

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • showID: The TMS ID of the show you are setting a reminder for.
  • shouldSet: A boolean which denotes whether the like should be set, or unset.

Notes:

You must know what the TMS ID for a show is, for this function to be useful to you. For the show the user clicked to arrive at your VApp, use VAPP.getShowInfo().

Invocation:

function setLikeCallback(message) { } 

//Set 

VAPP.setLike(setLikeCallback, 'SH005927330000', true); 

//Unset VAPP.setLike(setLikeCallback, 'SH005927330000', false); 

setReminder:

Description:

This function allows a VApp to set a reminder for the show that is passed in as episodeID.

Parameters:

callback: String

episodeID: String

shouldSet: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • episodeID: The TMS ID of the show you are setting a reminder for.
  • shouldSet: ‘YES’ if the reminder should be set, or ‘NO’ if unset.

Notes:

You must know what the TMS ID for a show is, for this function to be useful to you. For the show the user clicked to arrive at your VApp, use VAPP.getShowInfo().

Invocation:

function setReminderCallback(message) { } 
//Set 
VAPP.setReminder(setReminderCallback, 'SH005927330000', 'YES'); 

//Unset 

VAPP.setReminder(setReminderCallback, 'SH005927330000', 'NO'); 

setTitleBarImages:

Description:

This function allows a VApp to set an image to appear in the top bar of your VAPP.

Parameters:

callback: String

portraitImageToLoad: String

landscapeImageToLoad: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • portraitImageToLoad: A URL that points to the image to load in the portrait orientation.
  • landscapeImageToLoad: A URL that points to the image to load in the landscape orientation.

Notes:

The area for the two images are (200px, 40px) and (300px, 30px) respectively. It is recommended that you pass in 2 images that are (400px, 80px) and (600px, 60px) so they render well on retina capable devices.

You cannot display both a title bar image, and a title bar title, so if you call both functions, it will only display the images.

Invocation:


function setTitleBarImagesCallback(message) { } 

VAPP.setTitleBarImages(setTitleBarImagesCallback, 'http://placekitten.com/400/80', 'http://placekitten.com/600/60'); 

setTitleBarTitle:

Description:

This function allows a VApp to set the title of a VApp, in the top bar.

Parameters:

callback: String

title: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • title: Set the title that appears on the navigation bar of your VAPP.

Notes

You cannot display both a title bar image, and a title bar title, so if you call both functions, it will only display the images.

Invocation:


function setTitleBarTitleCallback(message) { } 
VAPP.setTitleBarTitle(setTitleBarTitleCallback, 'My Brand!'); 

setTitleBarSubTitle:

Description:

This function allows a VApp to set the subtitle of a VApp, in the top bar.

Parameters:

callback: String

title: String

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • subtitle: Set the subtitle that appears on the navigation bar of your VAPP.

Notes

You cannot display both a title bar image, and a title bar title, so if you call both functions, it will only display the images.

Invocation:

function setTitleBarSubTitleCallback(message) { }
 
VAPP.setTitleBarSubTitle(setTitleBarSubTitleCallback, 'My Brand!'); 

setWebViewShouldScrollWhenReachingEnd:

Description:

This function designates whether the VApp should “bounce” the webview which contains the VAPP when the bottom of the page is reached.

Parameters:

callback: String

scrolls: bool

  • callback:A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • scrolls: Set whether the VApp should scroll or not.

Notes

By default it is set to no.

Invocation:

function setWebViewShouldScrollWhenReachingEndCallback(message) { } 

//The webview will scroll once the user has reached it's vertical boundaries. 

VAPP.setWebViewShouldScrollWhenReachingEnd(setWebViewShouldScrollWhenReachingEndCallback, 'true'); 

showAd:

Description:

This function allows a VApp to display user targeted ads from the Viggle Ad inventory. It calls our ad server, retrieves the ad and dresses an html div with the information to be displayed.

If you choose to serve these ads in your application, you will be eligible for revenue sharing with Viggle. If your VApp contains this call and is accepted for distribution within Viggle, we will contact you regarding the terms of this revenue sharing agreement.

The ad call provided here will give you control over a non-monetizing demonstration advertisement intended to allow you to properly format the UI of your app. A call to a live ad server will be provided if your VApp is put into production.

Parameters:

callback: String

html element: DOM object

ad server url: String

  • callback: A function executed when the user visits and closes the Ad. Accepts a JSON parseable string containing diagnostic information.
  • html element: A DOM object, usually a div, that will be dressed with the ad content
  • ad server url: A string representing the ad server endpoint that will return the targeted ad content

Notes:

For development purposes use this address for the ad server url: ‘http://adserver.adtechus.com/?adrawdata/3.0/5386/2798901/0/16/ADTECH’

To use this VApp call, you will need to include the following helper JS file in your VApp:

<script src=http://assets.viggleassets.com/assets/b/3/5/5/b3552a70252b2c4faa90c88e60fe1008.js></script>

Invocation:

function showAdCallback(message) { } 
VAPP.showAd(showAdCallback, document.getElementById('mydiv'), "http://adserver.adtechus.com/?adrawdata/3.0/5386/2798901/0/16/ADTECH"); 

showModal:

Description:

This function allows a VApp to display a modal view with information, most commonly to alert a user that points have been added to his Viggle account.

Parameters:

callback: String

title: String

points: int

content: String

show check mark: Bool

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • title: The title for this modal dialog.
  • points: An integer which will show up to the user as how many points he earned.
  • content: The message you wish to display to the user.
  • show check mark: determines if you want to show a checkmark in the top left corner of the modal. True by default.

Notes:

points: This is not necessarily the amount of points fired off by an event, but just how many you wish to display to the user. For the most consistent experience, you should make those the same.

Invocation:

function showModalCallback(message) { } 
VAPP.showModal(showModalCallback, "Points update", 15, "I would like to tell you that you are my favorite user, keep it up!", true); 

whitelist:

Description:

This function sets which VAPPs the VAPP can load outside of the current VApp. This is necessary if you use the browser and/or view methods to navigate to different pages in your application or if you will be calling a different VApp.

Parameters:

callback: String

urls: Array

  • callback: A function executed when the method completes it’s action. Accepts a JSON parseable string containing diagnostic information.
  • urls: An array of VAPPs that the VAPP can access. These must be set explicitly.

Invocation:

function whitelistCallback(message) { } 

//White list other VAPPs you wish to load from this VApp 

VAPP.whitelist(whiteListCallback, ['http://www.myothervapp.com', 'http://vapp2.com']);