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.

Setting User Information

You can set user-specific information. This information will be displayed in your dashboard along with the automatically collected user properties. These methods can be called any time after calling start().


                                void setUserId(String userId)

Sets the application specific user identifier. Pass nil to log out the current user.

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 setUserProperty(final String propertyName, final Object propertyValue)

Sets a single property for the current user.

Parameters:
propertyName : The name of the property to set. Must be a String. propertyValue : The value of the property to set. Properties must be either Integer, Double, Float, String, Url, Boolean, Date, or a Collection of Strings.

Note: Property keys should be shorter than 256 characters and may not contain the dot ('.') or dollar ('$') signs - they will be trimmed. String values should be shorter than 1000 characters.


                                void setUserProperties(Map<String, Object> userProperties)

Sets multiple (key-value) properties for the current user.

Parameters:
userProperties : The user properties to set. Keys must be Strings. Properties must be either Integer, Double, Float, String, Url, Boolean, Date, or a Collection of Strings.

Note: Property keys should be shorter than 256 characters and may not contain the dot ('.') or dollar ('$') signs - they will be trimmed. String values should be shorter than 1000 characters.


                                void incUserProperty(String propertyName, double value)

Increment the value of a numeric property.

Parameters:
propertyName : The name of the user property value : The value to increment or decrement by (if negative)


                                void appendToUserProperty(String propertyName, String item)

Append an item to a list property.

Parameters:
propertyName : The name of the user property item : The item to append


                                void removeUserProperty(final String propertyName)

Unsets a property for the current user.

Parameters:
propertyName : The name of the user property


                                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


                                    Appsee.SetUserId("1234");



                                    Appsee.SetUserProperty("Role", "Administrator")

                                    Map<String, Object> props = new HashMap<String, Object>();

                                    props.put("Role", "Administrator");

                                    props.put("AmountPaid", 3.2);

                                    props.put("RegistrationDate", DateTime.Now());

                                    Appsee.SetUserProperties(props);


                                    Appsee.IncUserProperty("AmountPaid", 3);

                                    Appsee.AppendToUserProperty("VisitedCities", "New York");

                                    Appsee.RemoveUserProperty("Role");


                                    Appsee.SetUserId("1234");



                                    Appsee.SetUserProperty("Role", "Administrator")

                                    var props = new Dictionary<string, Java.Lang.Object>();

                                    props.Add("Role", "Administrator");

                                    props.Add("AmountPaid", 3.2);

                                    props.Add("RegistrationDate", DateTime.Now());

                                    Appsee.SetUserProperties(props);


                                    Appsee.IncUserProperty("AmountPaid", 3);

                                    Appsee.AppendToUserProperty("VisitedCities", "New York");

                                    Appsee.RemoveUserProperty("Role");


                                    Appsee.setUserId("1234");




                                    Appsee.setUserProperty("Role", "Administrator");

                                    Appsee.setUserProperties({"Role" : "Administrator",

                                    "AmountPaid" : 3.2,

                                    "RegistrationDate" : new Date()});


                                    Appsee.incUserProperty("AmountPaid", 3);

                                    Appsee.appendToUserProperty("VisitedCities", "New York");

                                    Appsee.removeUserProperty("Role");




                                    Appsee.setLocationDescription("Office");


                                    Appsee.setUserId("1234");




                                    Appsee.setUserProperties({"Role" : "Administrator",

                                    "AmountPaid" : 3.2,

                                    "RegistrationDate" : new Date()});


                                    Appsee.incUserProperty("AmountPaid", 3);

                                    Appsee.appendToUserProperty("VisitedCities", "New York");

                                    Appsee.removeUserProperty("Role");




                                    Appsee.setLocationDescription("Office");


                                    Appsee.setUserId("1234");




                                    Appsee.setUserProperty("Role", "Administrator");

                                    Appsee.setUserProperties({"Role" : "Administrator",

                                    "AmountPaid" : 3.2,

                                    "RegistrationDate" : new Date()});


                                    Appsee.incUserProperty("AmountPaid", 3);

                                    Appsee.appendToUserProperty("VisitedCities", "New York");

                                    Appsee.removeUserProperty("Role");




                                    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:.


                                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:
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


                                    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.


                                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


                                    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().


                                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


                                    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.


                                void addScreenAction(String 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


                                    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


                                    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".


                                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.

Code Example


                                    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.


                                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


                                    // 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.


                                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.


                                void installJavascriptInterface(WebView webView)

Installs the Appsee Javascript on the given WebView object.

Parameters:
webView : A WebView object.

Native Code Example


                                    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.


                                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


                                    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);