s3ePlayhaven.s4e

# Playhaven extension for Marmalade

include:

#include <s3eTypes.h>
#include "IwDebug.h"

enum s3ePHPurchaseResolutionType
{   
	S3ePHPurchaseResolutionBuy,   
	s3ePHPurchaseResolutionCancel,
	s3ePHPurchaseResolutionError,
	s3ePHPurchaseResolutionFailure
};

enum  s3ePHContentTransitionType
{
    s3ePHContentTransitionUnknown,
    s3ePHContentTransitionModal,
    s3ePHContentTransitionDialog
};

/**
 @name Playhaven callback definitions
*/

/**
	Playhaven callbacks, most callbacks are optional, Playhaven will function correctly without them. 
	You should implement S3EPH_CONTENT_UNLOCK_REWARD if configuring Playhaven to unlock rewards.
	You should implement S3EPH_CONTENT_MAKE_PURCHASE if configuring VGP in Playhaven
	
	note In Marmalade all callbacks are queued up and trigger after the next s3eDeviceYield()
	
	Your callback needs to be of the form int32 MyCallback(void *systemData,void *userData)
	You can specify userData when you register the callback, it is simply passed back to your callback and
	could be used to help the callback identify context.
    The return value you set is ignored in all cases.
	systemData has the following meaning depending on the specific callback.

	You can register for the following callback events by passing an s3eCallback format function
	to s3ePHRegisterCallback below.
	
	S3EPH_CONTENT_START - systemData is a (const char*) to the placement ID (set in Playhaven dashboard)
	Corresponds to the requestWillGetContent iOS Playhaven delegate
	The request is about to attempt to get content from the PlayHaven API. 
	
	S3EPH_CONTENT_RECEIVED - systemData is a (const char*) to the placement ID (set in Playhaven dashboard)
	Corresponds to the requestDidGetContent iOS Playhaven delegate
	The request received some valid content from the PlayHaven API. This will be the last callback a preloading request will receive, unless there is an error.
	
	S3EPH_CONTENT_WILL_DISPLAY - systemData is a (const s3ePHPublisherContent*)
	Corresponds to the contentWillDisplay iOS Playhaven delegate
	dismissReason will be NULL
	If there is content for this placement, it is loaded at this point. An overlay view appears over your app and a spinner indicates that the content is loading. 
	Depending on the transition type for your content, your view may or may not be visible at this time. If you haven't done this, you should mute any sounds and pause 
	any animations in your app. 	
	
	S3EPH_CONTENT_DID_DISPLAY - systemData is a (const s3ePHPublisherContent*)
	Corresponds to the contentDidDisplay iOS Playhaven delegate
	dismissReason will be NULL
	The content has been successfully loaded and the user is now interacting with the downloaded content view.
	
	S3EPH_CONTENT_DISMISSING - systemData is a (const s3ePHPublisherContent*)
	Corresponds to the contentDidDismissWithType iOS Playhaven delegate
	The URL, transition and closeButtonURL members will not be set.
	The content has successfully dismissed and control is being returned to your app. This can happen as a result of the user clicking on the close button or clicking on a 
	link that will open outside of the app. You may restore sounds and animations at this point.

	S3EPH_CONTENT_FAILED - systemData is a (const char*) containing the placement and error message concatenated
	Corresponds to the didFailWithError iOS Playhaven delegate
	If for any reason the content request does not successfully return some content to display or fails to load after the overlay view has appeared, the request stops and any visible 
	overlays are removed.
	
	S3EPH_CONTENT_UNLOCK_REWARD - systemData is a (const s3ePHReward*)
	Corresponds to the unlockedReward iOS Playhaven delegate
	PlayHaven allows you to reward users with virtual currency, in-game items, or any other content within your game. If you have configured unlockable rewards for your content 
	units, you will receive unlock events through this callback. It is important to handle these unlock events in every placement that has rewards configured.
	
	S3EPH_CONTENT_MAKE_PURCHASE - systemData is a (const s3ePHPurchase*)
	Using the Virtual Goods Promotion content unit (VGP), PlayHaven can be used to trigger In-App Purchase requests in your app using this callback.
	PlayHaven offers full-screen content units which advertise virtual goods. When a user clicks an ad, the PlayHaven Android SDK sends this callback to your game.
	note You must configure your "in app purchase" items on the PlayHaven Dashboard to enable this functionality.
	You are responsible for handling the purchase using the appropriate Store extension and then calling s3ePHReportResolution.
	Unless you call s3ePHReportResolution: the Playhaven content unit will stall, and your users may not be able to come back to your game after the Store extension has completed.
	
*/

/**
 @name Playhaven callback definitions
*/

/**
	Enum defining acceptable callback types - see above 
*/

enum s3ePHCallbackType
{
	S3EPH_CONTENT_START,
	S3EPH_CONTENT_RECEIVED,
	S3EPH_CONTENT_WILL_DISPLAY,
	S3EPH_CONTENT_DID_DISPLAY,
	S3EPH_CONTENT_DISMISSING,
	S3EPH_CONTENT_FAILED,
	S3EPH_CONTENT_UNLOCK_REWARD,
	S3EPH_CONTENT_MAKE_PURCHASE,
	S3EPH_MAX_ID
};

/**
Structure passed back to various content status callbacks
note The contents of this structure will be deallocated once it drops out of scope.

@param placement - placement ID for this content, see Playhaven dashboard
@param url
@param transition
@param closeButtonURLPath
@param dismissReason - only valid for S3EPH_CONTENT_DISMISSING, otherwise NULL, see Playhaven documentation for dismissal string types eg. PHPublisherContentUnitTriggeredDismiss
*/

struct s3ePHPublisherContent
{
	const char* placement;
	const char* url;
	s3ePHContentTransitionType transition;
	const char* closeButtonURLPath;
	const char* dismissReason;
};

/**
Structure passed to the S3EPH_CONTENT_UNLOCK_REWARD callback
note The contents of this structure will be deallocated once it drops out of scope.

@param name - The name of your reward as configured on the dashboard.
@param quantity - An integer representing the quantity associated with the reward.
@param receipt - A unique identifier that is used to detect duplicate reward unlocks. Your app should ensure that each receipt is only unlocked once.
*/

struct s3ePHReward
{
	const char* name;
	int quantity;
	const char* receipt;
};

/**
Structure passed to the S3EPH_CONTENT_MAKE_PURCHASE callback
note The contents of this structure will be deallocated once it drops out of scope.

@param productIdentifier - The product identifier for your purchase. This is a unique string used for Store Kit requests.
@param quantity - An integer representing the quantity associated with the purchase. 
@param receipt - A unique identifier.
*/

struct s3ePHPurchase
{
	const char* productIdentifier;
	int quantity;
	const char* receipt;
};

functions:

/**
 @name Initialisation of the Playhaven SDK
*/

/**
Initialise the Playhaven extension, call this function before using other functions.

@param token - your Playhaven app Token
@param secret - your Playhaven secret
*/

s3eResult s3ePlayhavenInitWithKeys(const char* token,const char* secret) S3E_RESULT_ERROR run_on_os_thread

/**
 Optional function to register your callbacks that Playhaven will call on certain events
 
 note Callbacks are queued up and trigger after the next s3eDeviceYield(). 
 @param callbackID A member of the s3ePlayhavenCallbackType enum
 @param callbackFn Your s3eCallback format function see callbacks definitions above for specifics
 @param userData Optional opaque pointer that will be passed back to your callback function in the userData parameter
*/
void s3ePHRegisterCallback(s3ePHCallbackType callbackID,s3eCallback callbackFn,void* userData);

/**
Your application should report each time that it comes to the foreground. PlayHaven uses these events to measure the click-through rate of your 
content units to help optimize the performance of your implementation. This request is asynchronous and may run in the background while your game is loading.
Call this when the app first opens and also ideally when the application moves into the foreground.
note Corresponds to [PHPublisherOpenRequest send] in iOS SDK

@param customUDID - Playhaven will use OpenUDID to identify this device by default, if you want to replace this with a custom UID pass it here or set it to NULL
*/
void s3ePHSendAppOpen(const char* customUDID) run_on_os_thread

/**
 @name Display of Playhaven Placement Content
*/

/**
Request and display content.
You request content for your app using your API token, secret, and a placement tag to identify the placement for which you are requesting content.
Placement means the placement tags set up in the Playhaven dashboard.
To receive callbacks during the request see the callbacks section.
note Corresponds to [PHPublisherContentRequest send] in iOS SDK

@param placement - The placement tags are set using the PlayHaven dashboard.
@param showOverlayImmediately - you can show the loading overlay immediately by setting showsOverlayImmediately property to YES. This is useful if you would 
like keep users from interacting with your UI while the content is loading.

*/
void s3ePHSendContentRequest(const char* placement,bool showOverlayImmediately) run_on_os_thread

/**
To make content requests more responsive, you may choose to preload a content unit for a given placement. This starts a request for a content unit without displaying it, 
preserving the content unit until you call s3ePHSendContentRequest for the same placement in your app. 
Placement means the placement tags set up in the Playhaven dashboard.
Preloading only works for the next content request for a given placement. If you are showing the same placement multiple times in your app, you will need to make 
additional preload requests after displaying that placement's content unit for the first time.
To receive callbacks during the request see the callbacks section
Note Corresponds to [PHPublisherContentRequest preload] in iOS SDK

@param placement - The placement tags are set using the PlayHaven dashboard.
*/

void s3ePHPreloadContentRequest(const char* placement) run_on_os_thread

/**
You can cancel any API request at any time using this function. This also cancels any open network connections and cleans up any views in the case of content 
requests. Canceled requests will not send any more callbacks once the cancel has executed - be aware however that with Marmalade the cancel request will be queued on a different 
thread and it will still be possible for in flight callbacks to arrive until that thread completes.

*/

void s3ePHCancelAllContentRequests() run_on_os_thread

/**
 @name Playhaven VGP and IAP
*/

/**
If you set up VGP and handle the S3EPH_CONTENT_MAKE_PURCHASE callback you *MUST* call this function once the store extension has completed or control may not return to
your app.
Implementation note To avoid the app having to handle the PHPurchase opaque pointer the extension will remember it and pair it up. It assumed not more than one PHPurchase 
request is going to be in flight at a time.

@param resolution - see s3ePHPurchaseResolutionType enum
*/

void s3ePHReportResolution(s3ePHPurchaseResolutionType resolution) run_on_os_thread

/**
@deprecated (to show a compiler warning)

Tracking in-app purchases
By providing data on your In-App Purchases to PlayHaven, you can track your users' overall lifetime value as well as track conversions from your Virtual Goods Promotion 
content units. To report successful purchases call this after a purchase has been successfully delivered.
note Corresponds to [PHPublisherIAPTrackingRequest send] in iOS SDK

@param product - string identifying the product
@param quantity - quantity of the product
@param resolution - see s3ePHPurchaseResolutionType
*/

void s3ePHSendPublisherIAPTrackingRequest(const char* product,int quantity,s3ePHPurchaseResolutionType resolution) run_on_os_thread

/**
 @name Playhaven "more_games" button
*/

/**
Add a notification view (notifier badge)
Adding a notification view to your More Games button can increase the number of More Games Widget opens for your game by up to 300%. 
Specify where you want to centre the badge and set testing to true if you want to see a test notification. 
Notification views will remain anchored to the center of the position they are placed in the view, even as the size of the badge changes. 
The extension will only support a single notifier badge. 

@param x - x centre of notification view
@param y - y centre of notification view
@param useGLView - only applies to iOS, on iOS Marmalade you will either be using the GL surface or the S3E UI surface depending on your App, select the correct view to attach the notifier badge to here
@param testing - Most of the time the API returns an empty response, which means a notification is not shown. You can see a sample notification by enabling testing.
*/

s3eResult s3ePHShowNotificationView(int x,int y,bool useGLView,bool testing) S3E_RESULT_ERROR run_on_os_thread

/** 
Cancel the notification view.
It is automatically cleared when you successfully launch a content unit. 
*/

void s3ePHClearNotificationView() run_on_os_thread

/**
Refresh the notification view.

@param testing - Most of the time the API returns an empty response, which means a notification is not shown. You can see a sample notification by enabling testing.
*/

void s3ePHRefreshNotificationView(bool testing) run_os_thread

/**
To comply with Apple policies for the use of device information, we've provided a mechanism for your app to opt-out of collection of UDID and MAC addresses. To set the opt out status for your app, use the following method.
You are responsible for providing an appropriate user interface for user opt-out. The default is to send user data.
note Corresponds to [PHAPIRequest setOptOutStatus:(BOOL)yesOrNo] in iOS SDK

@param on - true if opting out
*/
void s3ePHSetOptOutStatus(bool on) run_on_os_thread


/**
Tracking in-app purchases
By providing data on your In-App Purchases to PlayHaven, you can track your users' overall lifetime value as well as track conversions from your Virtual Goods Promotion 
content units. To report successful purchases call this after a purchase has been successfully delivered.
note This version of IAP tracking does receipt validation
note Corresponds to [PHPublisherIAPTrackingRequest send] in iOS SDK

@param product - string identifying the product
@param quantity - quantity of the product
@param resolution - see s3ePHPurchaseResolutionType
@param receiptData - pointer to binary receipt data
@param receiptSize - size of the receipt data
*/

// Must be at the bottom because for some reason to order= param isn't working
void s3ePHSendPublisherIAPTrackingRequestWithReceipt(const char* product, int quantity, s3ePHPurchaseResolutionType resolution, const void* receiptData, size_t receiptSize) order=1 run_on_os_thread