Workflows
Workflows & Examples
The following sections illustrate the implementation of basic use cases you may want to refer when integrating the ACTV8me iOS SDK into your project. Although you may choose from other content types, the samples are based on the delivery of redeemable offers.
Initialize SDK
All client interactions with the server require API credentials and configuration values provided to you upon SDK registration.
Provide API Credentials
Within the AppDelegate file, you need to set the API base URL, the API key, and the the audio fingerprint database URL.
The following example shows how to accomplish this after setting the values of such properties in the Info.plist file:
#import <Nucleus/Nucleus.h>
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *) launchOptions {
[NCAPIManager setBaseUrl:[[NSBundle mainBundle] objectForInfoDictionaryKey:@"ACTV8meBaseUrl"]];
[NCAPIManager setAPIKey:[[NSBundle mainBundle] objectForInfoDictionaryKey:@"ACTV8meApiKey"]];
[NCAPIManager setTriggerUrl:[[NSBundle mainBundle] objectForInfoDictionaryKey:@"ACTV8meFPDBUrl"]];
}
The setLogRequest property allows you to turn on/off SDK network logs. This should only be enabled for debugging purposes.
[[NCAPIManager sharedManager] setLogRequests:YES];
Register / Update Device
The ACTV8me backend requires each SDK client to register a device. If the device has already been registered, such device should be updated with its latest metadata.
The following method conveniently handles both scenarios:
[[NCAPIManager sharedManager] createOrUpdateDevice];
The SDK makes periodic requests to the backend to update device information and retrieve application settings. The interval at which these requests are made can be controlled by using the following method:
[NCAPIManager setUpdateDevicePeriod:60] // the minimum interval is 60 seconds;
User Authentication
Although optional, certain features of the ACTV8me platform (i.e. digital wallet, user profile, scratcher sets, etc) require the user to be authenticated. Therefore, you may want to provide authentication to uniquely identify your users.
If you do not currently have an authentication server for your application, you can leverage the ACTV8me Oauth 2.0 server to authenticate your users.
The following code snippet illustrates basic authentication logic:
Create User (email login)
user = [NCUser new];
user.email = @"[email protected]";
user.password = @"password";
user.login_method = @"email";
// Register user
[NCAPIManager registerUser:user callback:^(NSError *error){
// Your code here
}];
user is an instance of the NCUser class.
- When registering a new user, the DOB (Date Of Birth) and gender must follow these formats:
- DOB: "yyyy-MM-dd" (string) format .
- Gender: 1 (int) for "male" and 2 (int) for "female".
If your application already has an authentication provider, you may refer to the Syndicated Login method (read below).
Login User (email)
Users that have been registered via the ACTV8me authentication service can be logged in via the following method:
[NCAPIManager login:user callback:^(NSDictionary *response, NSError *error) {
if (!error) {
NSLog(@"log in successful");
}
}];
}
“NCAPIManager.user != null” can be called to find out whether or not the user is logged in. This method returns a NCUser object type.
Login User (syndicated)
In the ACTV8me ecosystem, a syndicated user is a user that has been registered using an external authentication provider. In this case, the ACTV8me backend "trusts" that the client has successfully authenticated the user, and allows the login of such user using a unique identifier.
user = [NCUser new];
user.external_id = @"ABCDF-1234567890"; // example unique identifier
user.login_method = @"syndicated";
[NCAPIManager login:user callback:^(NSDictionary *response, NSError *error) {
if (!error) {
NSLog(@"log in successful");
}
}];
The external ID can be any string that you consider unique for the user. The ACTV8me backend does not perform validation of this ID against the auth provider.
Get User Details
After a successful user login, you can get user account details by calling the following method:
[NCAPIManager getUserCallback:^(id response, NSError *error){
//your code here
}];
Note:
The SDK handles the authorisation requirement for this request.
Get User Profile Data
The user's profile data can be easily retrieved by calling the following method:
[NCAPIManager getUserPII:[NCAPIManager user] callback:^(id response, NSError *error){
//your code here
}];
Update User Profile
The SDK provides the following method to update the logged-in user profile
[NCAPIManager updateUser:[NCAPIManager user] callback:^(NSError *error){
//your code here
}];
Note: SDK only allows for the updating of DOB (Date oOf Birth) and Gender.
Logout User
If you decide to authenticate your users, you should also include a logout procedure. The following code snippet illustrates such logic:
[NCAPIManager logout:^(NSError *error){
if (!error) {
[NCContentManager clearWallet];
[[NCTriggerManager sharedManager] clearSignals];
[[UIApplication sharedApplication]
setApplicationIconBadgeNumber:0];
}
}
];
Audio Trigger Detection
If the content delivery for your app relies on the ACTV8me audio trigger detection, you may refer to the following steps:
- Create an instance of the VATriggerAudio class, register it with the NCTriggerManager and send confirmation to the NCTriggerDelegate protocol.
#import <ValenceAudio/VATriggerAudio.h>
- (void)viewDidLoad {
[super viewDidLoad];
// NCGenericTrigger objects need to be strongly referenced instance variables
NCGenericTriggerOptions *options = [NCGenericTriggerOptions new];
options.requestPermissionsOnRegister = NO;
self.audio = [[VATriggerAudio alloc] initWithOptions:options];
[self.audio setDelegate:self];
[[NCTriggerManager sharedManager] registerTrigger:self.audio];
[self.audio start];
}
- When listening to an audio source that has been either watermarked or fingerprinted by the ACTV8me encoding tools, the SDK should be able to detect and decode the unique identifier from the trigger signal, and request related content from the backend.
The following snippet illustrates the procedure around this use case:
- (void)trigger:(NCGenericTrigger *)trigger signal:(NCSignal *)signal
didCatchContent:(NSArray <NCContent *>*)content error:(NSError *)error {
if (!error) {
NSLog(@"found trigger %@ %@", signal.uuid, content);
}
}
To help reduce battery drainage, the ACTV8me backend provides the capability to attach a schedule to the audio listening service. This feature can be controlled from the ACTV8me Dashboard or via an API call. By default, the schedule is disabled, which results in the service to be always ON. When enabled, the SDK retrieves the schedule from the application settings and handles all the logic for enabling/disabling the audio service in the background.
Digital Wallet
The ACTV8me platform provides all the backend services you need to offer your users a digital wallet feature within your app. Every successful delivery of content to a user results in an entry on the ACTV8me database linking the user to such content, which becomes a wallet item.
Note:
In order to access the digital wallet, the user needs to be authenticated.
Retrieve wallet items
The user digital wallet is no more than a collection of content linked to the authenticated user upon successful delivery. Such collection can be retrieved by calling the following method:
[NCAPIManager contentGetAndFilterBy:nil callback:^(NSArray <NCContent >*responseModel, NSError error){
// Your code here
}];
Save content
If content is returned by the server after a "catch" request by the SDK, you may prompt the user to "save" such content into the user's digital wallet. The following snipppet illustrates the logic around this use case:
- (void)didAcceptOffer:(NCContent *)offer { // hypothetical method
[NCContentManager contentInsert:offer callback:^(NSArray<NCContent *>*content, NSError *error){
if (!error) {
NCContentStatus *status = [NCContentStatus new];
status.status = @(NCStatusAccept);
[NCContentManager contentUpdate:offer status:status];
}
}];
}
View content
Once the backend returns a valid offer to the client, you may display it to the user. The following logic shocases such routine:
- (void)didViewOffer:(NCContent *)offer { // hypothetical method
NCContentStatus *status = [NCContentStatus new];
status.status = @(NCStatusView);
[NCContentManager contentUpdate:offer status:status];
}
Redeem In-Store
When configuring an offer, a content admin can decide to make it available for redemption at the store. If so, the offer will contain redemption metadata that is used to render a barcode within the offer view. The intent to redeem in store is handled by the following logic:
- (void)didRedeemInstoreOffer:(NCContent *)offer { // hypothetical method
NCContentStatus *status = [NCContentStatus new];
status.status = @(NCStatusRedeemInStore);
[NCContentManager contentUpdate:offer status:status];
}
Redeem Online
When configuring an offer, a content admin may also allow for online redemption. If so, you may give your user the option to do so:
- (void)didRedeemOnlineOffer:(NCContent *)offer { // hypothetical method
NCContentStatus *status = [NCContentStatus new];
status.status = @(NCStatusRedeemOnline);
[NCContentManager contentUpdate:offer status:status];
}
Delete content
When implementing a digital wallet, it is important to give your users the ability to delete items they may no longer be interested in. The following logic exemplifies such routine:
- (void)didDeleteOffer:(NCContent *)offer { // hypothetical method
[NCContentManager contentDelete:offer callback:^(NSArray <NCContent*> *wallet, NSError *error){
if (!error) {
NSLog(@"offer deleted");
}
}];
}
Background Service Listening
Audio
The ACTV8me iOS SDK provides an audio service that will listen in the background so long as it is active. However, this service needs exclusive access to the microphone in order to run. This means that if a different process is using the microphone then the service will not be properly started. Conversely, if the service is running and a different process tries to access the microphone it will not be able to.
The start the audio detection service, use the following method:
[self.audio start];
To stop the audio detection service, use the following method:
[self.audio stop];
Note: audio is an instance of VATriggerAudio.
Beacon
The ACTV8me iOS SDK has the ability to detect signals emitted by beacons, and decode their unique ID, whic is then used to deliver related content.
As with the audio service, you may want to start the beacon detection service using the following method:
[self.beacon start];
To stop the beacon detection service, simply call below method:
[self.beacon stop];
Note: beacon is the instance of VATriggerBeacon.
Geofence
The ACTV8me iOS SDK has the ability to detect geofences and decode the their unique ID, which is later used to request related content.
As with the audio and beacon services, you may want to start the geofence detection service using the following method:
[self.geofence start];
To stop the geofence detection service, simply call below method:
[self.geofence stop];
Note: geofence is the instance of VATriggerGeofence.
Updated almost 4 years ago