Tag an Event in an iOS App (tagApplicationWithName)

You can tag an event to monitor custom activities in your mobile app by inserting a call to the tagging API. A custom activity for mobile apps starts and ends when the app reports specific events which match the events of an activity's signature file. If Aternity already reports these events by default, you do not need to add manual API calls. However, for some custom activities, you must manually tag and report those events using API calls.

Tag an event in your app using one of the following tagging APIs:

  • tagApplicationWithName tags an event which occurred in your app, like the tap of an icon. You specify the start of the event with StartPhase, and the end with EndPhase.

  • tagCancelledWithName tags a user interruption during the activity, like tapping Cancel on the screen. This is a different type of EndPhase, where the end is the interruption by the user. Depending on the activity definition, this could result in an incomplete activity.

  • tagErrorWithName reports an error during the activity. This is a different type of EndPhase, where the end is the occurrence of an error. You can add contextual details, like an error message or code, which can be picked up by the signature as part of its logic.

After tagging an event, you can optionally add contextual data if needed, then use reportTag to send the event to the server.

Reporting custom events from a mobile app which mark the start and end of an activity

For example, to measure the response time between the start of a login and its response, if those events are not automatically reported, insert an API to tag the login action, and add another API call to tag its response. When you report each tag to Aternity, the system matches them to the custom activity already in place, and then reports the response time in the dashboards. To create your own custom activities, contact Customer Services.

The tag APIs return a newly created AternityContext object, which you then send to the server using reportTag. You can add further data to the Context object, like the target server, or even the response time if the app knows this.

Tagging a custom event with the API

Before You Begin

Before you begin, ensure you have already done the following:

Method Definition

The tag APIs return a newly created AternityContext object, which you then send to the server using reportTag. These methods are defined as part of the Aternity class.

– (AternityContext *)tagApplicationWithName:(NSString*)tagName
                    withPhase:(enum AternityPhase)phase;
– (AternityContext *)tagCancelledWithName:(NSString*)tagName;
– (AternityContext *)tagErrorWithName:(NSString*)tagName;
enum AternityPhase
{AternityStartPhase, AternityEndPhase};
Parameter Description

tagName

Enter the name of the custom event which you are tagging.

phase

Choose whether this marks the start or end of the event:

  • AternityStartPhase signifies the start of the event.

  • AternityEndPhase signifies the end of the event.

You can theoretically bypass using AternityEndPhase to signify the start and end of an activity. You could send two different tagNames with a AternityStartPhase, where the activity signature finds and uses those tags to mark the start and end of the activity.

Example

The Aternity class provides the sharedManager method, which returns a singleton object. You should call the class's methods using this singleton object, to avoid manually creating and maintaining the Aternity object.

In Objective-C:

//Create an AternityContext object called "dl_start" which tags the start of "Download"
AternityContext *dl_start= [[Aternity sharedManager] tagApplicationWithName:@"Download"
                        withPhase:AternityStartPhase];

//You can also set some values in the context object before reporting it to the server
[dl_start setContextValue:self.urlText.text forKey:@"FileName"];
[dl_start setContextValue:[fileAtrrib objectForKey:@"NSFileSize"] forKey:@"FileSize"];

//Report the AternityContext object with its tag and contextuals to the server
[dl_start reportTag];

//When user taps Cancel, tell the server that the activity is canceled. 
//Optionally add contextuals here too.
AternityContext *dl_cancel= [[Aternity sharedManager] tagCancelledWithName:@"Download"];
[dl_cancel reportTag];

//Tag and report an error to the server.
AternityContext *dl_error = [[AternityAgent sharedManager] tagErrorWithName:@"Download"];
[dl_error reportTag];

In Swift:

//Create an AternityContext object called "dl_end" which tags the end of "Download"
var dl_end: AternityContext = Aternity.sharedManager().tagApplicationWithName("Download", 
                             withPhase:AternityEndPhase)

//You can also set some values in the context object before reporting it to the server
dl_end.setContextValue(self.urlText.text forKey:"FileName")
dl_end.setContextValue(fileAtrrib.objectForKey("NSFileSize") forKey:"FileSize")

//Report the AternityContext object with its tag and contextuals to the server
dl_end.reportTag()

//When user taps Cancel, tell the server that the activity is canceled.
//Optionally add contextuals here too.
var dl_cancel: AternityContext = AternityAgent.sharedManager().tagCancelledWithName("Download")
dl_cancel.reportTag()

//Tag and report an error to the server.
var dl_error: AternityContext = AternityAgent.sharedManager().tagErrorWithName("Download")
dl_error.reportTag()