You can add your own contextual data when you report a tagged event to Aternity, for use in the activity signature's internal logic. The setContextValue API adds a key value pair to the AternityContext object which you created earlier when you tagged an event.

For example, if you tagged the start of a file download, you can use setContextValue to add contextual data of the file size to be downloaded, so that the signature only starts the activity if the downloaded file is less than 1GB. Alternatively, if you are reporting an error tag, you can use the contextuals to send the error message or error code.

This fits into the wider picture of monitoring a custom activity as follows:

1. Tag a custom event with tagApplicationWithName to create an AternityContext object.

2. (Optional) Add a key and value as contextual data to the AternityContext object using setContextValue. You can assign any number of key-value pairs, where the key and its value are defined as strings.

3. Report the AternityContext object containing the tagged event and its contextual data using reportTag.

You can also use valueContextForKey to retrieve a key's value, and removeContextForKey to delete a key and its value.

Before You Begin

• The system requirements of the developer's computer must conform to those of the Aternity iOS Mobile SDK.

• The Aternity iOS Mobile SDK requires a mobile device with at least iOS 8 (iPhone 4 or earlier cannot run iOS 8).

• Integrate the Aternity iOS Mobile SDK into your app development environment.

• Include the Aternity.h header file (in Objective-C) into your source code file. To add it to a Swift project, use a bridging header (see Apple's documentation).

• Initialize the SDK either automatically (by adding Aternity.plist to your project) or manually using activateWithDictionary.

Method Definition

The setContextValue API adds a key value pair to the AternityContext object which you created earlier when you tagged an event. You can assign any number of key-value pairs, where the key and its value are defined as strings.

You can also use valueContextForKey to retrieve a key's value, and removeContextForKey to delete a key and its value.

@interface AternityContext : NSObject
- (void)setContextValue:(NSString *)value
                 forKey:(NSString *)aKey;

- (NSString *)valueContextForKey:(NSString *)aKey;

- (void)removeContextForKey:(NSString *)aKey;

- (void)reportTag;
@end

Example

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

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

//Report an error, add the reason as a contextual, and send it to the server.
var dl_error: AternityContext = AternityAgent.sharedManager().tagErrorWithName("Download")
dl_error.setContextValue("Timeout", forKey: "reason")
dl_error.reportTag()