Prepare the SDK for data validation (iOS)

To install Bazaarvoice Contextual Commerce on your iOS application, you will install, initialize, and configure the Contextual Commerce SDK to establish a connection between your app and Bazaarvoice. This article describes how to prepare the SDK to ensure basic functionality before proceeding with the full implementation.

In this phase, you will:

Include the SDK framework
Start the SDK using your site's configuration
Send page view and order data to Bazaarvoice
Send group assignment data to your analytics platform

Note: This guide covers the default iOS integration using Swift and UIKit. All code samples assume a Swift project with UIKit-based interfaces.

Install the SDK

Note: Please be aware for Contextual Commerce that variables and technical identifiers (for example, activateGranify(with:), GranifyInlineView) may retain the prefix or name Granify.

Add the GranifySDK framework to your Xcode project so it can interact with your app. This ensures the SDK is included in your build, authorized to run on Apple devices, and ready to be activated in the next step.

Create a “Frameworks” folder in Xcode
1. Open your project file in Xcode.
2. In the navigator area, open your project's context menu and select New folder.
3. Name the folder Frameworks.
4. Ensure the new folder is added to your project file.
Import the XCFramework into the Frameworks folder
1. Locate the GranifySDK.xcframework file.
2. Drag the file directly into the Frameworks folder or right-click the folder and select Add Files.
3. Select GranifySDK.xcframework then select Add.
Embed the GranifySDK framework in your project’s target
1. Navigate to your project settings, and select General.
2. Locate the GranifySDK.xcframework in the Frameworks, Libraries, and Embedded Content section.
3. Select Embed and Sign.
Link the framework with your project
1. Navigate to your project settings, and select Build Phases.
2. Locate the GranifySDK.xcframework in the Link Binary With Libraries section.
3. Add the GranifySDK.xcframework if it’s not already listed.
4. Verify the framework is set to Required.

Activate the SDK

The GranifySDK remains inactive until you turn it on, allowing you to enable or disable Contextual Commerce without major code changes. In this step, you will collect the configuration details that define how the SDK should recognize your app and direct shoppers to the right screen. Then, pass the configuration details to the SDK to activate it.

Caution: Do not call activateGranify until you have set up your event listeners. Refer to the Set up the Group Assignment event handler topic following this section.

Collect required information

Before you can activate the SDK, collect the following data points that will define how the SDK will recognize and interact with your app:

Site ID

The unique identifier for your site within the Contextual Commerce system. To obtain your Site ID, reach out to your account manager.
Child site ID (Optional)

If you manage multiple brands or sites within your app, child site IDs let Contextual Commerce separate data and perform site-specific configuration overrides.

Deep links

Deep links tell the SDK how to open specific pages in your app, such as a promotion, product detail page, or cart, after a shopper interacts with a campaign. You can define deep links using a static URL if the destination page can be opened with a fixed link. If the destination page requires additional parameters, such as product ID or SKU, use a link factory closure to define deep links.

Use the DeepLink array for all page types. Do not use the legacy productLinkBuilder alongside Deep Links, as this will cause configuration conflicts.

The following is an example of deep links defined by a static URL for a cart page and a link factory for a product page:

Copy Code

Code

let deepLinks = [
  DeepLink(pageType: .cart, link: URL(string: "com.mycompany.MyApp://cart")!),
  DeepLink(pageType: .product, linkFactory: { (params) in
      // do something to launch this page type
  }),
  ... // add links to all relevant page types
]

Create a configuration object

Once you have collected the required information above, gather it into a configuration object. This object tells the SDK how your app is structured and how to handle navigation between screens.

The following is an example of a configuration object with placeholder values:

Copy Code

Code

let deepLinks = [
  DeepLink(pageType: .cart, link: URL(string: "com.mycompany.MyApp://cart")!),
  DeepLink(pageType: .product, linkFactory: { (params) in
      // do something to launch this page type
  }),
  ... // add links to all relevant page types
]
let config = GranifyConfiguration(forSite: SiteIdentifier(identifier: "AbXyZ")!,
                                  childSiteId: SiteIdentifier(identifier: "SdFgH")!,
                                  deepLinks: deepLinks)
    }
try? Granify.activateGranify(with: config)

Call the Activate method

Activate the SDK by calling the activateGranify method. For more information about the method, refer to the activateGranify article.

Set up the Group Assignment event handler

In this step, you will register an event handler that is triggered whenever a shopper is assigned to a group. The event handler sends the group assignment directly to your analytics platform without any modifications.

Note: Call subscribeGroupAssigned before you call activateGranify. If the SDK activates and assigns a group before the client subscribes, the client will miss the group assignment event.

The Group Assignment event categorizes each shopper into one of two groups:

Test group
Shoppers who are eligible to receive campaigns.
Control group
Shoppers who are not eligible to receive campaigns and create a baseline for performance metrics.

Subscribe to Group Assigned event

Notify your app every time Contextual Commerce assigns a shopper to a group. Call the subscribeGroupAssigned(handler:) method to register the callback that will capture group assignment data. For more information, refer to subscribeGroupAssigned section of the class reference article.
Copy Code
Code
Granify.subscribeGroupAssigned { group in // log the chosen group with your metrics provider }
Forward group assignment data to your analytics

Forward the raw group assignment data directly to your analytics platform without any modifications to ensure your performance metrics are based on unaltered data. Since every client's analytics setup can be unique, this step is intentionally flexible.
1. Identify your analytics platform and refer to its documentation to determine which method or API call to use for tracking events.
2. Within your callback function, insert the code that forwards the group assignment data to your analytics platform.
3. Test your integration to ensure group assignment data is correctly flowing into your analytics platform.

Implement basic tracking functionality

For Contextual Commerce to make accurate decisions and deliver the right messages at the right time, it must know exactly what the shopper is viewing as they move through your application and whether they are placing orders.

In this step, you will set up the following two methods to enable the basic tracking functionality needed to prepare your SDK setup for QA review:

trackPageView
Notifies Contextual Commerce every time the shopper navigates to a new page or view within your app.
trackOrder
Captures every order successfully placed by shoppers, which is essential for measuring Contextual Commerce performance.

Track page views

The Contextual Commerce SDK cannot automatically detect in-app page changes. Track the actively viewed page to ensure Contextual Commerce shows the right campaigns on the right pages.

Call the trackPageView method to notify Contextual Commerce every time:

The application starts
The application resumes from background
A session starts (sessions automatically restart if the shopper returns after idling for more than 30 minutes)
A screen is presented to the user on any navigation path change

Note: Ensure the SDK is active when the application starts by calling activateGranify before you call trackPageView. This helps prevent issues related to campaigns not showing correctly.

The method requires you to provide information about the page being viewed:

mainScrollView: The scrollable area that shows which part of the page the shopper is viewing. This allows the SDK to monitor scrolling behavior and time spent in specific areas.

Note: For UIKit only, pass nil for SwiftUI.

pageIdentifier: The type of page the shopper is viewing and its unique path. For types that have multiple versions (Product, Collection, Blog), you must provide a unique identifier (such as, Product ID or Category Path) to distinguish between them.
getInsets: The callback that defines the safe area to display in-app campaigns. It should return the minimum margins from screen edges that must remain clear to prevent your app's UI from being occluded by any campaign techniques. This is re-calculated on device rotation.

Contextual Commerce recognizes the following types of pages:

home: The home page of the app.
product: A page that represents a single product tat might have multiple variations.
collection: A page that contains multiple products or child categories that users can select.
ensemble: A page that lists a small group of products, similar to a collection or a complete outfit, allowing products to be added to the cart.
search: A page that allows search (if that is a dedicated page) and the page that displays the search results.
blog: A topical, informational article that is not specifically related to purchasing products.
cart: A page that lists the contents of the cart, allowing the shopper to manage their cart and continue to complete their purchase.
checkout: A page that allows the shopper to complete their purchase.
flights: A special form of the product page used specifically for flight booking sites.
account: An admin page that allows the shopper to view past purchases and manage their account.
login: A page that allows the user to sign in or sign out.
info: A permanent informational page about the site, such as "About Us."
guide: A page that helps or guides shoppers through the purchase journey.
video: A page that is dedicated to video content.
other: Any page to which a specific page type does not apply.
receipt: A page shown after a completed checkout.
wishlist: A page that shows a current wishlist, or list of wishlists.

For more information about the trackPageView method, refer to the trackPageView section of the class reference article Opens in new tab .

The following is an example of the trackPageView method for a cart page:

Copy Code

Code

try? Granify.trackPageView(pageIdentifier: .cart, mainScrollView: myDetailsScrollView) {
  return UIEdgeInsets(top: 0, left: 0, bottom: menu.height, right: 0)
}

Track orders

Accurate order tracking is necessary for testing campaign functionality and calculating performance metrics. Given some apps have non-standard checkout flows, integrate this method in a way that fits your app to ensure every order event is forwarded.

Determine all points in your order process where an order is finalized.
Call the trackOrder method at these points to ensure every order is tracked.
Verify that the order data accurately reflects your internal metrics.

Note: Accurate order tracking ensures reliable metrics for performance evaluation, billing, and future campaign optimization. If your order flow involves background processing or delays, ensure the trackOrder method is only called after the order is fully confirmed.

The method requires you to provide information about the product(s) being ordered:

sku: The unique identifier for the specific product variant.
productId: The unique identifier for the parent product grouping.
title: The display name of the product.
price: The product's current selling price, including any discounts.
regularPrice: The product's standard price before any discounts are applied.
image: The URL pointing to the product's primary image.
url: The deep-link URL that opens the product's page within your app.

For more information about tracking orders, refer to the trackOrder section of the class reference article.

The following is an example of the trackOrder method:

Copy Code

Code

try? Granify.trackOrder(details: Order(orderNumber: "order123",
            currency: Currency.usd,
            lineItemsTotal: Price(amount: 250.00),
            subtotal: Price(amount: 250.00),
            totalTax: Price(amount: 20.00),
            totalShipping: Price(amount: 20.00),
            total: Price(amount: 290.00),
            lineItems: [
              Product(productId: "product1", sku: "SKU123", title: "Running Shoes", price: Price(amount: 50.00), regularPrice: Price(amount: 50.00), image: URL(string: "https://example.com/images/shoes")!, url: URL(string: "https://example.com/product/shoes")!, category: "Apparel"): 1,
              Product(productId: "product2", sku: "SKU234", title: "Headphones", price: Price(amount: 40.00), regularPrice: Price(amount: 40.00), image: URL(string: "https://example.com/images/headphones")!, url: URL(string: "https://example.com/product/headphones")!, category: "Electronics"): 4,
              Product(productId: "product3", sku: "SKU456", title: "Water Bottle", price: Price(amount: 10.00), regularPrice: Price(amount: 20.00), image: URL(string: "https://example.com/images/bottle")!, url: URL(string: "https://example.com/product/bottle")!, category: "Accessories"): 4
            ],
            discountCodes: [],
))