iOS SDK API Reference
Starting Appsee Tracking
The start call will initiate session tracking by the Appsee SDK.
Please notice that start must be called on the app's main thread.
apiKey : The API key of the current app
Please notice that start must be called on the app's main thread.
+(void)start:(NSString*)apiKey
Starts the Appsee agent for tracking the current session's data.
Parameters:apiKey : The API key of the current app
Setting User Information
You can set user-specific information for each session. This information will be displayed in your dashboard along with the video.
These methods can be called any time after calling Appsee start:.
userID : The application-specific user identifier
Note: User ID should not exceed 256 UTF-8 bytes.
latitude : Latitude in degrees.
longitude : Longitude in degrees.
horizontalAccuracy : Horizontal accuracy.
verticalAccuracy : Vertical accuracy.
description : A custom string representing the user's location.
+(void)setUserID:(NSString*)userID
Sets the application specific user identifier.
Parameters:userID : The application-specific user identifier
Note: User ID should not exceed 256 UTF-8 bytes.
+(void)setLocation:(double)latitude longitude:(double)longitude
horizontalAccuracy:(float)horizontalAccuracy
verticalAccuracy:(float)verticalAccuracy
Sets the current user location.
Parameters:latitude : Latitude in degrees.
longitude : Longitude in degrees.
horizontalAccuracy : Horizontal accuracy.
verticalAccuracy : Vertical accuracy.
+(void)setLocationDescription:(NSString*)description
Sets the current user location's description.
Parameters:description : A custom string representing the user's location.
Code Example
Objective-C
Swift
React Native
Appcelerator
Xamarin
PhoneGap
[Appsee setUserID:@"1234"];
[Appsee setLocationDescription:@"Office"];
Appsee.setUserID("1234");
Appsee.setLocationDescription("Office");
Appsee.SetUserId("1234");
Appsee.SetLocationDescription("Office");
Appsee.setUserId("1234");
Appsee.setLocationDescription("Office");
Appsee.setUserId("1234");
Appsee.setLocationDescription("Office");
Appsee.setUserId("1234");
Appsee.setLocationDescription("Office");
Hiding Sensitive Views
You can mark UIViews as sensitive, so that their contents will be hidden in the video.
These methods can be called any time after calling Appsee start:.
view : A UIView object which contains sensitive information.
view : A UIView object which no longer contains sensitive information.
Appsee automatically hides text fields contained in UIWebViews. To unhide a specific text element, you can add the 'appsee-ignore' class, i.e.:
To hide a specific element, such as an image, add the 'appsee-hide' class, i.e.:
+(void)markViewAsSensitive:(UIView*)view
Marks a view as sensitive. The view will be blanked out in the video (and also the keyboard attached to it).
Parameters:view : A UIView object which contains sensitive information.
+(void)unmarkViewAsSensitive:(UIView*)view
Unmark a view as sensitive. Unmarking a view will also prevent future auto-detected views from being masked.
Parameters:view : A UIView object which no longer contains sensitive information.
Appsee automatically hides text fields contained in UIWebViews. To unhide a specific text element, you can add the 'appsee-ignore' class, i.e.:
class="appsee-ignore"
To hide a specific element, such as an image, add the 'appsee-hide' class, i.e.:
class="appsee-hide"
Code Example
Objective-C
Swift
React Native
[Appsee markViewAsSensitive:myView];
Appsee.markView(asSensitive: myView)
Appsee.unmarkView(asSensitive: myView)
<Button ref='{ x => Appsee.markViewAsSensitive(x) }' />
Setting Application Screens
Appsee automatically detects the different screens in your app. However in some cases where screen detection is not available (for example in opengl apps) you can
set screens manually.
screenName : The name of the screen (ie: "WelcomeScreen").
Note: Screen name should not exceed 256 UTF-8 bytes.
(void)startScreen:(NSString*)screenName
Mark the appearance starting time of a new screen. This method should be usually called from the viewDidAppear: method.
Parameters:screenName : The name of the screen (ie: "WelcomeScreen").
Note: Screen name should not exceed 256 UTF-8 bytes.
Code Example
Objective-C
Swift
React Native
Appcelerator
Xamarin
PhoneGap
[Appsee startScreen:@"MyScreen"];
Appsee.startScreen("MyScreen");
Appsee.StartScreen("MyScreen");
Appsee.startScreen("MyScreen");
Appsee.startScreen("MyScreen");
Appsee.startScreen("MyScreen");
Adding Application Events
You can add timed application events, such as reaching at a specific screen or level.
You will see these events in your dashboard along with the video, and you will be able to filter videos according to these events. Adding events is also useful for controlling which sessions are recorded, using a recording condition. For example: you can choose to record sessions of users which reached a specific level.
These methods can be called any time after calling Appsee start:.
eventName : The name of the event (ie: "InAppPurchase").
eventName : The name of the event (ie: "Level").
properties : Key-value pairs with custom properties for the event. Properties must be NSNumbers, NSStrings, NSDates, NSURL, or NSNull. Keys must be NSStrings.
Note: The total size of event name, property key and value should not exceed 300 bytes (per property). Strings are UTF-8 encoded. Events that exceed this limit will be ignored.
Property keys may not contain the dot ('.') or dollar ('$') signs - they will be trimmed.
You will see these events in your dashboard along with the video, and you will be able to filter videos according to these events. Adding events is also useful for controlling which sessions are recorded, using a recording condition. For example: you can choose to record sessions of users which reached a specific level.
These methods can be called any time after calling Appsee start:.
+(void)addEvent:(NSString*)eventName
Add a timed application event (such as: user reached a specific level or screen).
Parameters:eventName : The name of the event (ie: "InAppPurchase").
+(void)addEvent:(NSString*)eventName withProperties:(NSDictionary*)properties
Add a timed application event (such as: user reached a specific level or screen) along with custom properties.
Parameters:eventName : The name of the event (ie: "Level").
properties : Key-value pairs with custom properties for the event. Properties must be NSNumbers, NSStrings, NSDates, NSURL, or NSNull. Keys must be NSStrings.
Note: The total size of event name, property key and value should not exceed 300 bytes (per property). Strings are UTF-8 encoded. Events that exceed this limit will be ignored.
Property keys may not contain the dot ('.') or dollar ('$') signs - they will be trimmed.
Code Example
Objective-C
Swift
React Native
Appcelerator
Xamarin
PhoneGap
[Appsee addEvent:@"Purchase"];
[Appsee addEvent:@"Purchase" withProperties:[NSDictionary dictionaryWithObjectsAndKeys:
@"Shoes", @"ItemType",
@"Nike", @"ItemModel",
[NSNumber numberWithDouble:3.2], @"Price",
[NSDate date], @"PurchaseDate",
nil]];
Appsee.addEvent("Purchase");
Appsee.addEvent("Purchase", withProperties: ["ItemType" : "Shoes",
"ItemModel" : "Nike",
"Price" : 3.2,
"PurchaseDate" : NSDate()])
Appsee.AddEvent("Purchase");
Appsee.AddEvent("Purchase", new NSDictionary(
"ItemType", "Shoes",
"ItemModel", "Nike",
"Price", 3.2,
"PurchaseDate", DateTime.Now()
));
Appsee.addEvent("Purchase");
Appsee.addEventWithProperties("Purchase", { "ItemType" : "Shoes",
"ItemModel" : "Nike",
"Price" : 3.2,
"PurchaseDate" : new Date()});
Appsee.addEvent("Purchase");
Appsee.addEvent("Purchase", { "ItemType" : "Shoes",
"ItemModel" : "Nike",
"Price" : 3.2,
"PurchaseDate" : new Date()});
Appsee.addEvent("Purchase");
Appsee.addEvent("Purchase", { "ItemType" : "Shoes",
"ItemModel" : "Nike",
"Price" : 3.2,
"PurchaseDate" : new Date()});
Adding Screen Actions
Appsee automatically detects actions performed on native UI components. To denote actions performed on non-native components you can manually tag custom screen actions.
actionName : The name of the action (ie: "MyButtonClick").
Note: Action name should not exceed 256 UTF-8 bytes.
(void)addScreenAction:(NSString*)actionName
Add a custom action to the current screen.
Parameters:actionName : The name of the action (ie: "MyButtonClick").
Note: Action name should not exceed 256 UTF-8 bytes.
Code Example
Objective-C
Swift
React Native
Appcelerator
Xamarin
PhoneGap
[Appsee addScreenAction:@"MyButtonClick"];
Appsee.addScreenAction("MyButtonClick");
Appsee.AddScreenAction("MyButtonClick");
Appsee.addScreenAction("MyButtonClick");
Appsee.addScreenAction("MyButtonClick");
Appsee.addScreenAction("MyButtonClick");
Controlling Video Recording
You can control video recording using the following methods.
The stop/pause/resume are optional and should be only called when you explicitly want to override this behavior:
+(void)stop
Stops the current video (session tracking will continue). Usually, this method shouldn't be called unless you explicitly want to stop recording. A new video recording will begin when the app is launched to the foreground.
+(void)pause
Pause recording of the video. To resume, call 'resume'.
+(void)resume
Resume recording of the video.
Code Example
Objective-C
Swift
React Native
Appcelerator
Xamarin
PhoneGap
[Appsee pause];
[Appsee resume];
Appsee.pause();
Appsee.resume();
Appsee.Pause();
Appsee.Resume();
Appsee.pause();
Appsee.resume();
Appsee.pause();
Appsee.resume();
Appsee.pause();
Appsee.resume();
Opt-Out / Delete Data
By default all users are opted-in for tracking. You can control whether tracking is enabled or not for a specific user.
If setOptOutStatus was called with "YES" then all Appsee calls will be ignored until it will be set back to "NO".
status : Indicated whether to opt-out the user from tracking
If setOptOutStatus was called with "YES" then all Appsee calls will be ignored until it will be set back to "NO".
+(void)setOptOutStatus:(BOOL)status
Sets the opt-out status.
Parameters:status : Indicated whether to opt-out the user from tracking
+(BOOL)getOptOutStatus
Returns the current opt-out status, the default value is "NO".
+(BOOL)deleteCurrentUserData
Delete all local and remote data for the current user. This method also unsets the current active user, and opts out this device from future tracking.
Note: this method performs a synchronous call to the Appsee servers and is therefore recommended to be performed on a side thread..
The method returns a boolean value stating whether deletion was successful. Failure may occur in case the Appsee servers cannot be reached (in case there is no connectivity) - and the method should be retried.
The method returns a boolean value stating whether deletion was successful. Failure may occur in case the Appsee servers cannot be reached (in case there is no connectivity) - and the method should be retried.
Code Example
Objective-C
Swift
React Native
Appcelerator
Xamarin
PhoneGap
BOOL status = [Appsee getOptOutStatus];
[Appsee setOptOutStatus:YES];
let status = Appsee.getOptOutStatus();
Appsee.setOptOutStatus(true);
bool status = Appsee.getOptOutStatus();
Appsee.setOptOutStatus(true);
var status = Appsee.getOptOutStatus();
Appsee.setOptOutStatus(true);
var status = Appsee.getOptOutStatus();
Appsee.setOptOutStatus(true);
var status = Appsee.getOptOutStatus();
Appsee.setOptOutStatus(true);
Notifications
Appsee notifications will enable you to get notified once specific Appsee events occur.
Return "NO" in order to prevent the session from starting
sessionId : The Appsee Id of the tracked session
isVideoRecorded : Indicates whether or not the session is video recorded
sessionId : The Appsee Id of the tracked session
Return Value:
Return "NO" in order to prevent the session from ending (ie: when user is in a call in a Voip app)
sessionId : The Appsee Id of the tracked session
screenName : The name of the new detected screen.
Return Value:
Return the original screen name to do nothing. Return nil to ignore the screen. Return a different screen name to rename it.
appseeSessionStarting
Fired once Appsee is about to start a new session.
Return Value:Return "NO" in order to prevent the session from starting
appseeSessionStarted
Fired once Appsee has started tracking a new session.
Notification Parameters:sessionId : The Appsee Id of the tracked session
isVideoRecorded : Indicates whether or not the session is video recorded
appseeSessionEnding
Fired once Appsee is about to finish a session.
Notification Parameters:sessionId : The Appsee Id of the tracked session
Return Value:
Return "NO" in order to prevent the session from ending (ie: when user is in a call in a Voip app)
appseeSessionEnded
Fired once Appsee has completed tracking a session.
Notification Parameters:sessionId : The Appsee Id of the tracked session
appseeScreenDetected
Fired once Appsee has detected a new screen. You can instruct Appsee to ignore the new screen (by returning nil) or to rename the detected screen (by returning a different screen name). See the code examples below for more details.
Notification Parameters:screenName : The name of the new detected screen.
Return Value:
Return the original screen name to do nothing. Return nil to ignore the screen. Return a different screen name to rename it.
Code Example
Objective-C
Swift
Xamarin
// Set your AppDelegate as the Appsee delegate
@interface MyAppDelegate : UIResponder <AppseeDelegate>
[Appsee setDelegate:self];
// Implement the delegate methods for which you want to get notifications
-(BOOL)appseeSessionStarting
{
// To prevent a session from ending under some condition
if ([self someLogic])
return NO;
return YES;
}
-(void)appseeSessionStarted:(NSString *)sessionId videoRecorded:(BOOL)isVideoRecorded
{
// Use sesssionId and isVideoRecorded
}
-(BOOL)appseeSessionEnding:(NSString *)sessionId
{
// To prevent a session from ending under some condition
if ([self someLogic:sessionId])
return NO;
return YES;
}
-(void)appseeSessionEnded:(NSString *)sessionId
{
// Use sesssionId and isVideoRecorded
}
-(NSString *)appseeScreenDetected:(NSString *)screenName
{
// To ignore a new screen
if ([self someLogic1:screenName])
return nil;
// You can also change the screen's name
if ([self someLogic2:screenName])
return @"MyScreen";
// Default implementation should keep screen as is
return screenName;
}
// Set your AppDelegate as the Appsee delegate
class AppDelegate: UIResponder, ... , AppseeDelegate
Appsee.setDelegate(self);
// Implement the delegate methods for which you want to get notifications
func appseeSessionStarting() -> Bool
{
// To prevent a session from ending under some condition
if (someLogic())
return false
return true
}
func appseeSessionStarted(_ sessionId: String!, videoRecorded isVideoRecorded: Bool)
{
// Use sesssionId and isVideoRecorded
}
func appseeSessionEnding(_ sessionId: String!) -> Bool
{
// To prevent a session from ending under some condition
if (someLogic(sessionId))
return false
return true
}
func appseeSessionEnded(_ sessionId: String!)
{
// Use sesssionId and isVideoRecorded
}
func appseeScreenDetected(_ screenName: String!) -> String!
{
// To ignore a new screen
if (someLogic1(screenName))
return nil
// You can also change the screen's name
if (someLogic2(screenName))
return "MyScreen"
// Default implementation should keep screen as is
return screenName
}
// Follow the 3 steps below to enable Appsee notifications in Xamarin:
// 1. In your AppDeleagate, also implement the IAppseeDelegate interface:
public class AppDelegate : UIApplicationDelegate,
IUISplitViewControllerDelegate, IAppseeDelegate
// 2. Implement the following methods:
public bool SessionStarting()
{
// Your code here
return true;
}
public void SessionStarted(string sessionId, bool isVideoRecorded)
{
// Your code here
}
public bool SessionEnding(string sessionId)
{
// Your code here
return true;
}
public void SessionEnded(string sessionId)
{
// Your code here
}
// 3. In FinishedLaunching, set the Appsee delegate:
Appsee.Delegate = this;
Controlling Session Lifetime
You can control the session lifetime and upload timing using the following methods. Note - by default, a session starts when the app is in the foreground, and finished when the app is minimized to the background or crashes.
The following methods should only be called if you explicitly want to override this behavior. The session lifetime notifications may also be useful for altering session lifetime.
verifyBackground : Finish the session only if app is in background (pass 'NO' unless you have a Voip app).
shouldUpload : Upload the session immediately, or wait until the app is in the background.
+(void)finishSession:(BOOL)verifyBackground upload:(BOOL)shouldUpload
Stops the current session and uploads it (in the background). Usually, this method shouldn't be called unless you
explicitly want to stop recording and force uploading at some point in your app, before the user minimizes it.
Parameters:verifyBackground : Finish the session only if app is in background (pass 'NO' unless you have a Voip app).
shouldUpload : Upload the session immediately, or wait until the app is in the background.
+(void)forceNewSession
Starts a new session (if not already running). Usually, this method shouldn't be called unless you
explicitly want to start a new session at some point in your app, before it returns to foreground.
+(void)upload
Upload previous sessions. This method should not be called unless your app is never in the background and you
want to upload sessions on the foreground.
WebView Javascript Interface
You can call Appsee methods from within a WebView, using Javascript. To do so, call installJavascriptInterface with the WebView object, and then an 'Appsee' object will be available in Javascript, exposing the native methods.
webView : A UIWebView or WKWebView object.
+(void)installJavascriptInterface:(UIView*)webView
Installs the Appsee Javascript on the given WebView object.
Parameters:webView : A UIWebView or WKWebView object.
Native Code Example
Objective-C
Swift
Xamarin
[Appsee installJavascriptInterface:myWebView];
Appsee.installJavascriptInterface(myWebView);
Appsee.installJavascriptInterface(myWebView);
Supported Javascript Method Examples
Javascript
Appsee.setUserId('User1')
Appsee.startScreen('My Screen')
Appsee.addEvent('MyEvent')
Appsee.addEvent('MyEvent', JSON.stringify({'Type': 'Show', 'Amount': 16}))
Appsee.pause()
Appsee.resume()
Appsee.setLocation(1, 2, 3, 4)
Appsee.setLocationDescription('My Location')"
Appsee.addScreenAction('My Action')
Appsee.set3rdPartyId('Adobe', '1234', false)
3rd Party Integrations
Appsee enables integration with 3rd party platforms by either sending an Appsee Id to the 3rd party platform, or by sending a 3rd party Id to Appsee.
Please note that this feature is only available in Appsee's Enterprise Plans.
systemName : The 3rd party system name (ie: "Adobe")
isPersistent : Whether the identifier should be persistent across sessions.
externalID : The 3rd party system identifier to set
systemName : The 3rd party system name (ie: "Adobe")
isPersistent : Whether the identifier should be persistent across sessions.
Note: externalID should not exceed 256 UTF-8 bytes.
Please note that this feature is only available in Appsee's Enterprise Plans.
+(NSString *)generate3rdPartyID:(NSString *)systemName
persistent:(BOOL)isPersistent
Generates a unique ID for an external 3rd party system. This method should be usually called right after the start: method.
Parameters:systemName : The 3rd party system name (ie: "Adobe")
isPersistent : Whether the identifier should be persistent across sessions.
+(void)set3rdPartyID:(NSString *)externalID
forSystem:(NSString *)systemName persistent:(BOOL)isPersistent
Generates a unique ID for an external 3rd party system. This method should be usually called right after the start: method.
Parameters:externalID : The 3rd party system identifier to set
systemName : The 3rd party system name (ie: "Adobe")
isPersistent : Whether the identifier should be persistent across sessions.
Note: externalID should not exceed 256 UTF-8 bytes.
Code Example
Objective-C
Swift
React Native
Appcelerator
Xamarin
PhoneGap
NSString* id = [Appsee generate3rdPartyID:@"Adobe" persistent:YES];
[Appsee set3rdPartyID:@"1234" for:@"Adobe" persistent:YES];
var id = Appsee.generate3rdPartyID("Adobe", persistent: true);
Appsee.set3rdPartyID("1234", forSystem: "Adobe", persistent: true);
String id = Appsee.Generate3rdPartyId("Adobe", true);
Appsee.Set3rdPartyId("1234", "Adobe", true);
var id = Appsee.generate3rdPartyId("Adobe", true);
Appsee.set3rdPartyId("1234", "Adobe", true);
var id = Appsee.generate3rdPartyId("Adobe", true);
Appsee.set3rdPartyId("1234", "Adobe", true);
var id = Appsee.generate3rdPartyId("Adobe", true);
Appsee.set3rdPartyId("1234", "Adobe", true);
OpenGL APIs
In OpenGL projets, in addition to calling Appsee start:, the following methods are used:
glView : The GL view to be rendered.
includeUIKit : Whether to include UIKit elements to the video, on top of the OpenGL elements. Default = YES.
+(void)appendGLFrame:(UIView*)glView includeUIKitElements:(BOOL)includeUIKit;
Append the GL render buffer to the video. Should be called right before calling 'presentRenderbuffer:'.
If you have more than one render buffer, bind it first using glBindRenderbufferOES. By default, UIKit elements which appear on top of the GL layer (such as buttons / alert views) are rendered to the video as well, unless stated otherwise.
Parameters:If you have more than one render buffer, bind it first using glBindRenderbufferOES. By default, UIKit elements which appear on top of the GL layer (such as buttons / alert views) are rendered to the video as well, unless stated otherwise.
glView : The GL view to be rendered.
includeUIKit : Whether to include UIKit elements to the video, on top of the OpenGL elements. Default = YES.
+(void)startRenderLoop;
Mark the starting of the render loop. This method is optional and should be called only if calling appendGLFrame: alone results in empty videos.
This should be called right after binding a render buffer, and before drawing objects onto it. After drawing the objects, call presentRenderBuffer:.