Tag and Report an Event in an iOS App (tagApplicationWithName, reportTag)

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.

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 an iOS app which mark the start and end of an activity

For example, to measure the response time between the start of a sign in and its response, if those events are not automatically reported, insert an API to tag the sign in action, and add another API call to tag its response. When you report each tag to Aternity, it 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.

Tagging a custom event with the API

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

  • tagApplicationWithName tags an event which occurred in your app, like the start of a sign in. 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.

If the app reports a start event but does not report an end event, the activity ends with a timeout.

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

The AternityContext object is defined as follows:

@interface AternityContext : NSObject
- (void)reportTag;
- (void)setContextValue:(NSString *)value
                 forKey:(NSString *)aKey;
- (NSString *)valueContextForKey:(NSString *)aKey;
- (void)removeContextForKey:(NSString *)aKey;
@end
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.

Before reporting, you can optionally add further data to the Context object, like a search term, or a file size, or anything else which you want to send to the activity's signature waiting on the server side.

In Objective-C:

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

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

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

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

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

In Swift:

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

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

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

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

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