Android 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.
void start()
Starts the Appsee agent for tracking the current session's data.
Appsee requires the API key to reside in the app's Manifest file. If, for some reason, you cannot put your API key there, you may use the overload which accepts an API key.
Appsee requires the API key to reside in the app's Manifest file. If, for some reason, you cannot put your API key there, you may use the overload which accepts an API key.
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 start().
userID : The application-specific user identifier
Note: User ID should not exceed 256 UTF-8 bytes and must not contain any personal data (e.g. name, email, phone number)..
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(String userId)
Sets the application specific user identifier.
Parameters:userID : The application-specific user identifier
Note: User ID should not exceed 256 UTF-8 bytes and must not contain any personal data (e.g. name, email, phone number)..
void setLocation(double latitude, double longitude,
float horizontalAccuracy, float verticalAccuracy)
Sets the current user location.
Parameters:latitude : Latitude in degrees.
longitude : Longitude in degrees.
horizontalAccuracy : Horizontal accuracy.
verticalAccuracy : Vertical accuracy.
void setLocationDescription(String description)
Sets the current user location's description.
Parameters:description : A custom string representing the user's location.
Code Example
Java
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");
Masking Sensitive Views
You can mark Views 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 View object which contains sensitive information.
view : A View object which no longer contains sensitive information.
void markViewAsSensitive(View view)
Marks a view as sensitive. The view will be blanked out in the video (and also the keyboard attached to it).
Note: When using findViewById(int id) to find the view to be marked as sensitive,
please make sure that the view is properly initialized and a non-null value is returned as the View object.
Parameters:Note: When using findViewById(int id) to find the view to be marked as sensitive,
please make sure that the view is properly initialized and a non-null value is returned as the View object.
view : A View object which contains sensitive information.
void unmarkViewAsSensitive(View view)
Unmark a view as sensitive.
Parameters:view : A View object which no longer contains sensitive information.
Code Example
Java
React Native
Appsee.markViewAsSensitive(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(String screenName)
Mark the appearance starting time of a new screen. This method should be usually called from the activiry's onResume() method.
Parameters:screenName : The name of the screen (ie: "WelcomeScreen").
Note: Screen name should not exceed 256 UTF-8 bytes.
Code Example
Java
React Native
Appcelerator
Xamarin
PhoneGap
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 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 can only be Integer, Double, Float, String, Url, Boolean, or Date.
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 start().
void addEvent(String 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(String eventName, Map<String, Object> 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 can only be Integer, Double, Float, String, Url, Boolean, or Date.
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
Java
React Native
Appcelerator
Xamarin
PhoneGap
Appsee.addEvent("Purchase");
Map<String, Object> props = new HashMap<String, Object>();
props.put("ItemType", "Shoes");
props.put("ItemModel", "Nike");
props.put("Price", 3.2);
props.put("PurchaseDate", new Date());
Appsee.addEvent("Purchase", props);
Appsee.AddEvent("Purchase");
var props = new Dictionary<string, Java.Lang.Object>();
props.Add("ItemType", "Shoes");
props.Add("ItemModel", "Nike");
props.Add("Price", 3.2);
props.Add("PurchaseDate", DateTime.Now());
Appsee.AddEvent("Purchase", props);
Appsee.addEvent("Purchase");
Appsee.addEventWithProperties("Purchase", { "ItemType" : "Shoes",
"ItemModel" : "Nike",
"Price" : 3.2,
"PurchaseDate" : new Date()});
Appsee.addEvent("Purchase");
Appsee.addEvent("Purchase", { "ItemType" : "Shoes",
"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
Java
React Native
Appcelerator
Xamarin
PhoneGap
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
Java
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());
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 "true" then all Appsee calls will be ignored until it will be set back to "false".
status : Indicated whether to opt-out the user from tracking
If setOptOutStatus was called with "true" then all Appsee calls will be ignored until it will be set back to "false".
void setOptOutStatus(boolean status)
Sets the opt-out status.
Parameters:status : Indicated whether to opt-out the user from tracking
boolean getOptOutStatus()
Returns the current opt-out status, the default value is "false".
boolean 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
Java
React Native
Appcelerator
Xamarin
PhoneGap
boolean 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.
ShouldStartSession : Change this to "false" 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
ShouldEndSession : Change this to "false" 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.
onAppseeSessionStarting
Fired once Appsee is about to start a new session.
Notification Parameters:ShouldStartSession : Change this to "false" in order to prevent the session from starting
onAppseeSessionStarted
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
onAppseeSessionEnding
Fired once Appsee is about to finish a session.
Notification Parameters:SessionId : The Appsee Id of the tracked session
ShouldEndSession : Change this to "false" in order to prevent the session from ending (ie: when user is in a call in a Voip app)
onAppseeSessionEnded
Fired once Appsee has completed tracking a session.
Notification Parameters:SessionId : The Appsee Id of the tracked session
onAppseeScreenDetected
Fired once Appsee has detected a new screen. You can instruct Appsee to ignore the new screen (by setting the key value to null) or to rename the detected screen (by overriding the its value). See the code examples below for more details.
Notification Parameters:ScreenName : The name of the new detected screen.
Code Example
Java
Xamarin
// In your App's Application class, add the following code to the onCreate method
Appsee.addAppseeListener(new AppseeListener()
{
@Override
public void onAppseeSessionStarting(AppseeSessionStartingInfo startingInfo)
{
// To prevent a session under some condition
if (someLogic())
startingInfo.setShouldStartSession(false);
}
@Override
public void onAppseeSessionStarted(AppseeSessionStartedInfo sessionInfo)
{
String sessionId = sessionInfo.getSessionId();
boolean videoRecorded = sessionInfo.isVideoRecorded();
}
@Override
public void onAppseeSessionEnding(AppseeSessionEndingInfo sessionInfo)
{
String sessionId = sessionInfo.getSessionId();
// To prevent a session from ending under some condition
if (someLogic(sessionId))
sessionInfo.setShouldEndSession(false);
}
@Override
public void onAppseeSessionEnded(AppseeSessionEndedInfo sessionInfo)
{
String sessionId = sessionInfo.getSessionId();
}
@Override
public void onAppseeScreenDetected(AppseeScreenInfo screenInfo)
{
// To ignore a new screen
if (someLogic1())
screenInfo.setScreenName(null);
// You can also change the screen's name
if (someLogic2())
screenInfo.setScreenName("MyScreen"));
}
});
// Follow the 2 steps below to enable Appsee notifications in Xamarin:
// 1. Implement the IAppseeListener interface:
public class AppseeListener : Java.Lang.Object, IAppseeListener
{
public void OnAppseeSessionStarting(AppseeSessionStartingInfo appseeSessionStartingInfo)
{
// TODO: What should the app do when a session is starting
}
public void OnAppseeScreenDetected(AppseeScreenDetectedInfo appseeScreenDetectedInfo)
{
// TODO: What should the app do when a screen is detected
}
public void OnAppseeSessionStarted(AppseeSessionStartedInfo appseeSessionStartedInfo)
{
// TODO: What should the app do when a session has started
}
public void OnAppseeSessionEnding(AppseeSessionEndingInfo appseeSessionEndingInfo)
{
// TODO: What should the app do when a session is ending
}
public void OnAppseeSessionEnded(AppseeSessionEndedInfo appseeSessionEndedInfo)
{
// TODO: What should the app do when a session has ended
}
}
// 2. Just before the call to Appsee.Start, add the Appsee listener:
Appsee.AddAppseeListener(new AppseeListener());
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 'false' unless you have a Voip app).
shouldUpload : Upload the session immediately, or wait until the app is in the background.
void finishSession(boolean verifyBackground, boolean 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 'false' 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 WebView object.
void installJavascriptInterface(WebView webView)
Installs the Appsee Javascript on the given WebView object.
Parameters:webView : A WebView object.
Native Code Example
Java
Xamarin
Appsee.installJavascriptInterface(myWebView);
Appsee.installJavascriptInterface(myWebView);
Supported Javascript Method Examples
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.
systemName : The 3rd party system name (ie: "Adobe")
externalID : The 3rd party system identifier to set
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.
String generate3rdPartyID(String systemName, boolean 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(String systemName, String externalID, boolean 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")
externalID : The 3rd party system identifier to set
isPersistent : Whether the identifier should be persistent across sessions.
Note: externalID should not exceed 256 UTF-8 bytes.
Code Example
Java
React Native
Appcelerator
Xamarin
PhoneGap
String id = Appsee.generate3rdPartyId("Adobe", true);
Appsee.set3rdPartyId("Adobe", "1234", true);
String id = Appsee.Generate3rdPartyId("Adobe", true);
Appsee.Set3rdPartyId("Adobe", "1234", true);
var id = Appsee.generate3rdPartyId("Adobe", true);
Appsee.set3rdPartyId("Adobe", "1234", true);
var id = Appsee.generate3rdPartyId("Adobe", true);
Appsee.set3rdPartyId("Adobe", "1234", true);
var id = Appsee.generate3rdPartyId("Adobe", true);
Appsee.set3rdPartyId("Adobe", "1234", true);