Digital Analytics

iOS: Tagging an application with the Digital Analytics SDK

This page outlines each tag function and parameters for the Acoustic Digital Analytics SDK. iOS applications are tagged by using native Objective-C methods for tag creation and firing.

Each tag has required parameters with a maximum length. If a required parameter is missing or a value is greater than the length identified, the SDK will return false and will attempt to send data to the server.

Page view tag

The Page View tag is used to capture clickstream data as the visitor moves from page to page within the site. A Page View tag tells Digital Analytics that someone viewed a page that is uniquely identified by the Digital Analytics 'Page ID' collected as parameter 1. The Page View tag also captures data that is related to onsite keyword searches.

The following table contains the Page View tag parameters:

Parameter
Description
Length

Page ID

Required. Uniquely identifies the page. This can be any alphanumeric string and should be set according to the agreed upon page naming conventions.

256

Category ID

Optional. Category ID for the leaf node to which this page belongs. This should match with a category ID sent in the CDF file.

256

Search term

Optional. Onsite search term that was used to generate the search results page.

256

Search result

Optional. Number of results that are returned by the keyword search. This value should equal the total results for this search across all results pages. If the search returned no results, this value be "0."

10

Attributes

Optional. A string array of up to 50 attribute values accessible in Explore reporting.

256 per value

cm_mmc

Optional. Use this parameter on the first page view of the session to flag a session as a Marketing Center session (MMC). Four delimited values should be passed in this parameter (-_-").

256

Examples
Examples of using the Page View tag for iOS applications.

Defining all parameters:

[ DigitalAnalytics firePageView : @"AND:PAGEID" 
category : @"AND:CATID" searchTerm : @"boots" searchResult : @"123"
attributes :[ NSArray arrayWithObjects : @"att1" ,  @"att2" , @"" , @"att4"
 nil ]  cmmmc :[ NSArray arrayWithObjects : @"cmmmc1" ,
@"cmmmc2" , @"cmmmc3" , @"cmmmc4" nil ]];

Defining null values for categoryID, search term, search results, attributes, and cm_mmc:

[ DigitalAnalytics firePageView : @"AND:PAGEID"
 category : nil  searchTerm : nil searchResult : nil attributes : nil , nil ] 
 cmmmc : nil ];

Product view tag

The Product View tag captures information about views of product detail pages. The Product View tag should be called on the lowest level detail page for products, which is typically the Product Details page. You can view example Product View tags below.

These are the Product View tag parameters:

Parameter
Description
Length

Page ID

Required. Uniquely identifies the page. This can be any alphanumeric string and should be set according to the agreed upon page naming conventions.

256

Product ID

Required. Uniquely identifies the product. This can be any alphanumeric string.

256

Product name

Required. Name of the product being viewed.

256

Category ID

Optional. Category ID for the leaf node to which this page belongs. This should match with a category ID sent in the CDF file.

256

Attributes

Optional. A string array of up to 50 attribute values accessible in Explore reporting.

256 per value

Example
Here is an example of using the Product View tag for iOS:

[ DigitalAnalytics fireProductview : @"AND:PID1" 
productId : @"AND:PROD1" productName : @"AND:PNAME" category : @"AND:CAT1"
attributes :[ NSArray arrayWithObjects : @"attribute1" ,  @"attribute2" ,
 nil ]];

Shop Action 5 tag

The Shop Action 5 tag captures data about selected products and which products are present in a shopping cart if any when the cart is viewed.

These are the Shop Action 5 tag parameters:

Parameter
Description
Length

Product ID

Required. Uniquely identifies the product. This can be any alphanumeric string.

256

Product name

Required. Name of the product being viewed.

256

Quantity

Required. Quantity of this product currently selected or viewed in a cart.

8

Unit base price

Required. Price of each unit of the product. This value should be a decimal number and should not include a dollar sign ($).

16.2

Category ID

Optional. Category ID for the leaf node to which this page belongs. This should match with a category ID sent in the CDF file.

256

Currency code

Required. Digital Analytics supports capturing different currencies for purchases under a single client ID. Even if you are not sending multiple currency types, the currency code parameter is required. A currency code that conforms to the ISO4217 specification must be sent in this parameter. See http://www.xe.com/iso4217.php for reference.

N/A

Attributes

Optional. A string array of up to 50 attribute values accessible in Explore reporting.

256 per value

Example
Here is an example of using the Shop Action 5 tag for iOS applications:

[ DigitalAnalytics fireShopAction5 : @"AND:PROD1" 
productName : @"AND:PRODNAME" quantity : @"1" baseUnitPrice : @"9.98" 
category : @"AND:CAT1" currencyCode : @"USD" attributes :
:[ NSArray arrayWithObjects : @"attribute1" ,  @"attribute2" ,  nil ]];

Shop Action 9 tag

The Shop Action 9 tag captures data about what products were purchased by a customer. Like the Shop Action 5 tag, one tag should be sent for each product line item purchased. These tags should be sent on the receipt or other completion page confirming a successful order.

These are the Shop Action 9 tag parameters:

Parameter
Description
Length

Product ID

Required. Uniquely identifies the product. This can be any alphanumeric string.

256

Product name

Required. Name of the product being viewed.

256

Quantity

Required. Quantity of this product currently selected or viewed in a cart.

6

Unit base price

Required. Price of each unit of the product. This value should be a decimal number and should not include a dollar sign ($).

16.2

Category ID

Optional. Category ID for the leaf node to which this page belongs. This should match with a category ID sent in the CDF file.

256

Order ID

Required. Order ID for the order to which this line belongs. This should match the Order ID in the accompanying Order Tag.

64

Order subtotal

Required. Subtotal for the order to which line item belongs. This should not include shipping and handling or tax and should match the Order Subtotal in the accompanying Order Tag. This value should be a decimal number and should not include a dollar sign ($). The Order Subtotal should match the sum of Quantity * Unit Price for all Shop Action 9 tags (products) purchased in this order.

16.2

Customer ID

Required. Customer ID for the customer who purchased the product. This should match the Customer ID field in the accompanying Order Tag.

256

Currency code

Required. Digital Analytics supports capturing different currencies for purchases under a single client ID. Even if you are not sending multiple currency types, the currency code parameter is required. A currency code that conforms to the ISO4217 specification must be sent in this paramter. See http://www.xe.com/iso4217.htm for reference.

N/A

Attributes

Optional. A string array of up to 50 attribute values accessible in Explore reporting.

256 per value

Example
Here is an example of using the Shop Action 9 tag for iOS applications:

[ DigitalAnalytics fireShopAction9 : @"AND:PID1" 
productName : @"AND:PRODNAME" quantity : @"1" 
baseUnitPrice : @"9.99" category : @"AND:CAT1" 
orderId : @"ORDERID123" orderSubTotal : @"9.99" 
customerId : @"CUSTOMERID" currencyCode : @"USD" 
attributes : :[ NSArray arrayWithObjects : @"att1" ,  @"att2" ,  @"" ,  @"att4" ,  
nil ]];

Order tag

The Order tag captures order header information such as Registration ID, order ID, order subtotal, and shipping and handling. The Order tag should be sent on the receipt page confirming order completion.

These are the Order tag parameters:

Parameter
Description
Length

Order ID

Required. Order ID for the order to which this line belongs. This should match the Order ID in the accompanying Order Tag.

64

Order subtotal

Required. Subtotal for the order to which line item belongs. This should not include shipping and handling or tax and should match the Order Subtotal in the accompanying Order Tag. This value should be a decimal number and should not include a dollar sign ($). The Order Subtotal should match the sum of Quantity*Unit Price for all Shop Action 9 tags (products) purchased in this order.

16.2

Shipping charge

Required. Shipping and Handling for this order.

16.2

Customer ID

Required. Customer ID for the customer who purchased the product. This should match the Customer ID field in the accompanying Order Tag.

256

Customer city

Optional. City of the billing address for this customer.

256

Customer state

Optional. State of the billing address for this customer.

256

Customer postal code

Optional. Postal code of the billing address for this customer.

256

Currency code

Required. Digital Analytics supports capturing different currencies for purchases under a single client ID. Even if you are not sending multiple currency types, the currency code parameter is required. A currency code that conforms to the ISO4217 specification must be sent in this parameter. See http://www.xe.com/iso4217.htm for reference.

N/A

Attributes

Optional. A string array of up to 50 attribute values accessible in Explore reporting.

256 per value

Example
Here is an example of using the Order tag for iOS applications:

[ DigitalAnalytics fireOrder : @"ORDERID" subtotal : @"9.99"
 shippingCharge : @"4.99" customerId : @"CUSTOMERID" customerCity : @"AUSTIN"
 customerState : @"TX" customerZip : @"78735" currencyCode : @"USD" 
attributes :[ NSArray arrayWithObjects : @"att1" ,  @"att2" ,  @"" ,  @"att4" ,  
nil ]];

Registration tag

The Registration tag creates a Lifetime Visitor Experience Profile (LIVE Profile) by associating a single common Registration ID with the Acoustic Digital Analytics permanent cookie set in every browser visit to the tagged site.

The full fireRegistration API contains the customer ID, email address, customer city, customer state, customer postal code, customer country, and any additional attributes:

+ (BOOL)fireRegistration:(NSString *)customerId email:(NSString *)email 
customerCity:(NSString *)customerCity customerState:(NSString *)customerState 
customerZip:(NSString *)customerZip customerCountry:(NSString*)customerCountry 
attributes:(NSArray *)attributes;

These are the Registration tag parameters:

Parameter
Description
Length

Customer ID

equired. Customer ID for the customer who purchased the product. This should match the Customer ID field in the accompanying Order Tag.

256

Email address

Optional. Email address of the billing address for this customer.

256

Customer city

Optional. City of the billing address for this customer.

256

Customer state

Optional. State of the billing address for this customer.

256

Customer postal code

Optional. Postal code of the billing address for this customer.

256

Customer country

Optional. Country of the billing address for this customer.

256

Attributes

Optional. A string array of up to 50 attribute values accessible in Explore reporting.

256 per value

Registration attribute 50
Registration Attribute 50 is reserved to syndicate an opt-in status for a registered visitor.

By using information recorded in the Digital Analytics Registration tag attributes, you can determine your visitors' opt-in or out status for email communications. As a best practice, alias attribute 50 as contactConsent to reduce the odds of it being repurposed.

Note:

The -_- delimiter cannot set apart individual opt-in or opt-out instructions. To send more than one opt-in or opt-out instruction, you must use multiple registration tags.

Tagging values for Attribute 50

Attribute value
Value options (case insensitive)

Channel values

email, mobile, sms

Instruction values

opt-in, opt-out, [null]

Example registration attribute usage
Attribute Slot: 50

Attribute Alias: contactConsent

Attribute Value: email | opt-in

Example
Here is an example of using the Registration tag for iOS applications:

[ DigitalAnalytics fireRegistration : @"CUSTOMERID" 
email : @"[email protected]" customerCity : @"AUSTIN" customerState : @"TX"
customerZip : @"78735" customerCountry : @"US" attributes :[ NSArray arrayWithObjects : 
@"att1" ,  @"att2" ,  @"" ,  @"att4" ,  nil ]];

Element tag

The Element tag and its associated reports provide organizations with the flexibility to track interaction with various intrapage elements and how these elements drive objective attainment. Below are some examples of elements that could be tracked using the Element tag:

  • Portlets
    • Search portlets
    • News portlets
  • AJAX Detail Hovers
    • Product detail hover-overs
    • Customer review hover-overs
  • Video Plays
    • Play
    • Stop
    • Rewind
  • Dynamic Page Content
    • Price slider bars
    • Brand filter checkboxes
    • Feature selectors
    • Page or Form error messages
  • Clicks on File Downloads or 3rd Party Content or Banners
    • PDF downloads
    • 3rd Party Banners or Content
      These are the Element tag parameters:
Parameter
Description
Length

Element ID

Required. The unique identifier or name for the Element and the value that will be displayed in the Elements report.

50

Element category

Optional. The unique identifier or name for the Element and the value that is displayed in the Elements report. 50-character limit. This limit is in 'characters', which vary in byte length depending on encoding.

50

Attributes

Optional. A string array of up to 50 attribute values accessible in Explore reporting.

256 per value

Example
Here is an example of using the Element tag for iOS applications:

[ DigitalAnalytics fireElement : @"AND:EID" elementCategory : @"AND:ECAT" 
attributes :[ NSArray arrayWithObjects : @"att1" ,  @"att2" ,  @"" ,  @"att4" ,  
nil ]];

Conversion Event tag

The Conversion Event tag is employed for tracking general non-commerce conversion events. The Conversion Event tag is used to populate values in the Conversion Events Reports and to create Key Segments. This tag and the reports it populates enable an analysis of a wide variety of site activities.

Following are some examples of events that could be tracked via the Conversion Event Tag:

  • Increase site stickiness
    • Play online game
    • View account information
    • Use online calculator
    • Use trip planner
    • Use comparison tool
  • Improve self-service
    • Sign up for bridal registry
    • Download help documents
    • Download form
    • Download marketing information
  • Improve retention marketing
    • Register for specific newsletter
    • Sign up for Webinar
    • Add items to wish list
    • Set email alerts
  • Multichannel behavior
    • Use store locator
    • Visit the contact us page
    • Initiate chat session
    • Register for callback
      These are the Conversion Event tag parameters:
Parameter
Description
Length

Event ID

Required. A unique identifier for the type of conversion, such as Account Creation or Special Registration. The value that is passed in the tag is the value that is displayed in the Digital Analytics reports.

256

Action type

Required. A value of 1 or 2 depending upon whether a conversion initiation or a successful conversion completion is generated. A value of 1 should be used when an event is initiated. A value of 2 should be used when an event is successfully completed. Single-Step conversions should be represented by a value of 2.

1

Event category

Optional. Allows grouping of event IDs into categories. The value that is passed in the tag is the value that is displayed in reports. The Event Category ID is self-contained and not related to the Category Definition File contents (CDF).

256

Event points

Optional. A point value used in establishing an arbitrary value for a converison. The point value allows relative weighting of and Event's initiation and completion. For example, a visitor initiating a low value event might be work 5 points, whereas a visitor completing a high value event might be worth 50 points.

16

Attributes

Optional. A string array of up to 50 attribute values accessible in Explore reporting.

256 per value

Example
Here is an example of using the Conversion Event tag for iOS applications:

[ DigitalAnalytics fireConversionEvent : @"/unit_test/iossdk/Event Id/ALL/" 
actionType : @"2" eventCategory : @"iossdk" eventPoints : @"10" 
attributes :[ NSArray arrayWithObjects : @"att1" ,  @"att2" ,  @"" ,  @"att4" ,
nil ]];

Manual Impression tag

Use the Manual Impression tag to collect marketing impressions for individual tracked Onside Marketing Links (Site Promotions or Real Estate).

Manual Impression tags are typically implemented in conjunction with a related Manual Link Click tag. One Impression tag is called for each related Site Promotion or Real Estate link object on a given page.

Common Use Case:

  • Manual 'Link Click' tags have been implemented to track JavaScript, AJAX, Flash, Silverlight, or other non-HTML/HREF link objects with Site Promotions and Real Estate parameters: equivalent 'Manual Impression' tags must be implemented if impression tracking is wanted for the related link objects.

These are the Manual Impression tag parameters:

Parameter
Description
Value

Page ID

Required. Uniquley identifies the originating page. This can be any alphanumeric string and should be set according to the agreed upon page naming conventions.

256

Site promotion

Site Promotion (cm_sp) marketing link parameter. Optional. A string array of values promotionGroup-_-promotion-_-link.

256

Real estate promotion

Real estate (cm_re) marketing link parameter. Optional. A string array of values pageVersion-_-pageArea-_-link.

256

Example
Here is an example of using the Manual Impression tag for iOS applications:

[ DigitalAnalytics fireImpression : @"PAGEID" 
cmsp: [ NSArray arrayWithObjects : @"ONE" ,  @"TWO" , @"THREE" ,  nil ]  
cmre: [ NSArray arrayWithObjects : @"ONE" ,  @"TWO" , @"THREE" ,  nil ]];

Manual Link Click tag

The Manual Link Click tag is used when the automated collection of link click data does not occur and LIVEview or Site Promotions/Real Estate reporting is desired for the affected links. Digital Analytics testing tools, including Tag Bar/Tag Monitor and Implementation Test Tool (ITT) can assist in determining if automatic Link Click tags are generated for the links in question.

These are the Manual Link Click tag parameters:

Parameter
Description
Length

Page ID

Required. Uniquely identifies the originating page. This can be any alphanumeric string and should be set according to the agreed upon page naming conventions.

256

Link name

Optional. Name attribute of the link. If link has no name, then use href.

256

Link href

Required. Link href. This parameter should contain any site promotion (cm_sp) or real estate (cm_re) parameters.

256

Example
Here is an example of using the Manual Link Click tag for iOS applications:

[ DigitalAnalytics fireLinkClick : @"PAGEID" linkName : @"LINKNAME" link : 
@"/HOME/END.HTML" ];

Updated 12 days ago


iOS: Tagging an application with the Digital Analytics SDK


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.