SPBrandEngageClient Class Reference
Inherits from | NSObject |
Conforms to | SPBrandEngageWebViewDelegate UIAlertViewDelegate |
Declared in | SPBrandEngageClient.h SPBrandEngageClient.m |
Overview
Provides methods to request and show BrandEngage offers, notifies its delegate of the availability of offers and of changes in the status of the engagement.
Before requesting offers, make sure of having set your app ID, current user ID and currency name, as well as one of your objects as the delegate. At this point you can determine if offers are available with requestOffers. If your delegate is notified that offers are available, run them by invoking startWithParentViewController:, and your delegate will be notified when the engagement has closed. When the engagement is over you must restart the process, querying if offers are available, before you run any engagement again.
To check for new virtual coins earned by the user, given you’ve set your VCS key, use SPVirtualCurrencyServerConnector.
%warning%
Warning: Offer availability (requestOffers) cannot be requested while an engagement is running. Call canRequestOffers if you’re not sure that this instance is in a state in which a request for offers is possible.
Tasks
Other Methods
-
appId
Your SponsorPay application ID.
property
This is the app ID assigned to you by SponsorPay. -
userId
ID of the current user of your application.
property
This string must uniquely identify the current user to the BrandEngage and virtual currency server systems. -
currencyName
Name of your virtual currency.
property
This is a human readable, descriptive name of your virtual currency.
Receiving asynchronous callbacks
-
delegate
Instance of one of your classes implementing the SPBrandEngageClientDelegate protocol, which will be notified of offers availability and engagement status.
property
Controlling notifications to the user
-
shouldShowRewardNotificationOnEngagementCompleted
Whether the SDK should show a toast-like notification to the user when they come back to your application after completing an engagement.
property
Turning on or off the use of the Unique Device Identifier
-
__deprecated
This property is deprecated and will be removed from a future SDK release.
property
The SponsorPaySDK does not fetch anymore the device’s UDID, and modifying the value of this property doesn’t change the behavior of the SDK. Starting May 1 2013 Apple’s App Store will reject submissions of new apps or updates to already existing apps that access the UDID.
Creating an SPBrandEngageClient instance
-
– initWithAppId:userId:currencyName:delegate:
This initializer has been deprecated and will be removed from a future SDK release. Please don’t initialize instances of this class directly, rather access them through [SponsorPaySDK brandEngageClient] or [SponsorPaySDK brandEngageClientForCredentials:]
Requesting offers
-
– canRequestOffers
Returns whether this instance is in a state in which it’s possible to query the server for offers availability.
-
– requestOffers
Queries the server for BrandEngage offers availability.
Running offers
-
– canStartOffers
Returns whether this instance is in a state in which it’s possible to start running an engagement.
-
– startWithParentViewController:
Starts running an available engagement.
Determining if it is safe to modify parameters
-
– canChangePublisherParameters
Determines whether it is possible to add or modify, at the point of invocation, this instance’s custom parameters specified with setCustomParamWithKey:value:
Setting arbitrary custom parameters
-
– setCustomParamWithKey:value:
Sets a custom key and value to be sent to the server on the next request for offers availability.
Properties
__deprecated
This property is deprecated and will be removed from a future SDK release.
The SponsorPaySDK does not fetch anymore the device’s UDID, and modifying the value of this property doesn’t change the behavior of the SDK. Starting May 1 2013 Apple’s App Store will reject submissions of new apps or updates to already existing apps that access the UDID.
@property (assign) BOOL shouldSendUDID __deprecated
Declared In
SPBrandEngageClient.h
appId
Your SponsorPay application ID.
This is the app ID assigned to you by SponsorPay.
@property (readonly, retain, nonatomic) NSString *appId
See Also
Declared In
SPBrandEngageClient.h
currencyName
Name of your virtual currency.
This is a human readable, descriptive name of your virtual currency.
@property (readonly, retain, nonatomic) NSString *currencyName
See Also
Declared In
SPBrandEngageClient.h
delegate
Instance of one of your classes implementing the SPBrandEngageClientDelegate protocol, which will be notified of offers availability and engagement status.
@property (assign) id<SPBrandEngageClientDelegate> delegate
See Also
Declared In
SPBrandEngageClient.h
shouldShowRewardNotificationOnEngagementCompleted
Whether the SDK should show a toast-like notification to the user when they come back to your application after completing an engagement.
@property (assign) BOOL shouldShowRewardNotificationOnEngagementCompleted
Discussion
An example notification would be “Thanks! Your reward will be payed out shortly”.
Default value is YES.
Declared In
SPBrandEngageClient.h
Instance Methods
canChangePublisherParameters
Determines whether it is possible to add or modify, at the point of invocation, this instance’s custom parameters specified with setCustomParamWithKey:value:
- (BOOL)canChangePublisherParameters
Return Value
YES if the properties can be modified at this point, NO otherwise.
Discussion
These publisher parameters cannot be added or modified while the server is being queried or an engagement is running. In these cases a call to setCustomParamWithKey:value: will have no effect.
Declared In
SPBrandEngageClient.h
canRequestOffers
Returns whether this instance is in a state in which it’s possible to query the server for offers availability.
- (BOOL)canRequestOffers
Return Value
YES if a request for offers can be currently initiated, NO otherwise. If NO is returned, a call to requestOffers will notify your delegate of an error.
Discussion
Offer availability cannot be requested while an engagement is running or the server is currently being queried. Call this method if you’re not sure that if this instance is in a state in which a request for offers is possible.
Declared In
SPBrandEngageClient.h
canStartOffers
Returns whether this instance is in a state in which it’s possible to start running an engagement.
- (BOOL)canStartOffers
Return Value
YES if an engagement can be initiated, NO otherwise.
Discussion
Most of the time you won’t have to call this method, but if you’ve lost track of whether this instance can start showing an engagement, this will let you know.
An engagement or offer cannot be started while another one is active, while the server is being queried, or after another engagement has closed if new offers have not been requested with requestOffers.
See Also
Declared In
SPBrandEngageClient.h
initWithAppId:userId:currencyName:delegate:
This initializer has been deprecated and will be removed from a future SDK release. Please don’t initialize instances of this class directly, rather access them through [SponsorPaySDK brandEngageClient] or [SponsorPaySDK brandEngageClientForCredentials:]
- (id)initWithAppId:(NSString *)appId userId:(NSString *)userId currencyName:(NSString *)currencyName delegate:(id<SPBrandEngageClientDelegate>)delegate
Declared In
SPBrandEngageClient.h
requestOffers
Queries the server for BrandEngage offers availability.
- (BOOL)requestOffers
Return Value
YES if a request for offers was initiated, NO if the request cannot be initiated. If NO is returned, this call had no effect and you need to invoke this method again when a request for offers is possible.
Discussion
Before you start running an engagement, you must call requestOffers and wait until your code is notified that offers are indeed available.
The answer to the request will be delivered asynchronously to your code via the registered SPBrandEngageClientDelegate.
Offer availability cannot be requested while an engagement is running or the server is currently being queried. Call canRequestOffers if you’re not sure that this instance is in a state in which a request for offers is possible.
See Also
Declared In
SPBrandEngageClient.h
setCustomParamWithKey:value:
Sets a custom key and value to be sent to the server on the next request for offers availability.
- (BOOL)setCustomParamWithKey:(NSString *)key value:(NSString *)value
Parameters
- key
Arbitrary key name for the custom param to set.
- value
Arbitrary value string for the custom param to set.
Return Value
YES if the parameter was set, NO otherwise.
See Also
Declared In
SPBrandEngageClient.h
startWithParentViewController:
Starts running an available engagement.
- (BOOL)startWithParentViewController:(UIViewController *)parentViewController
Parameters
- parentViewController
Your own view controller which will act as presenting or parent view controller for the engagement player.
Return Value
YES if the engagement will start, NO otherwise.
Discussion
The engagement player will take over the screen while the engagement is running. Its view controller will be shown as a modal child of your own view controller.
If the offer cannot be run (because requestOffers wasn’t previously called or it didn’t report available offers) this call will return NO.
Declared In
SPBrandEngageClient.h