Prepare the SDK for data validation (Android)

To integrate Bazaarvoice Contextual Commerce into your Android app, 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 Contextual Commerce 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 Android integration using Groovy and Kotlin. All code samples assume a Groovy project with views-based interfaces.

Install the SDK

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

Configure your project's repository

Open the Project-level build.gradle file
Locate the allprojects block

Add a local Maven repository that points at your unzipped GranifyAndroidSDK folder:

Copy Code

Groovy

allprojects {
        repositories {
            maven {
                url "<path to GranifyAndroidSDK folder>"
            }
            ...
        }
    }

Add the Granify SDK dependency
1. Open the app-level build.gradle file
2. In the dependencies section, add the following:
  Copy Code
  Groovy
  dependencies { ... implementation 'com.granifyinc:granifysdk:<current_version>' ... }
3. Replace the placeholder with the specific SDK version folder name. Go to GranifyAndroidSDK/com/granifyinc/granifysdk/ and locate the folder named in the X.Y.Z format. You can also open maven-metadata-local.xml and locate the version string within the <release> tags: <release>X.Y.Z</release>
Sync your project
1. Open Android Studio
2. Select Sync Now when prompted, or select File>Sync Project with Gradle Files
3. Download the SDK and integrate it into your app

Activate the SDK

The GranifySDK stays inactive until you turn it on. This gives you the control to activate or disable Contextual Commerce without making any 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 that configuration to the SDK to activate it.

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's identifier, 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.
- Application context
  
  Your application context that will be used to generate a preference file named Granify.
- Code version
  
  Your application's version string, for example 1.3.0 .

For more information about the required information, refer to Configuring Granify.

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.

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

val config = GranifyConfiguration(
  applicationContext = activity,
  siteId = SiteIdentifier("ABC12"),
  childSiteId = SiteIdentifier("XYZ12"),
  codeVersion = "1.3.0"
 )

Call the Activate method

Activate the SDK by calling the activateGranify method in your application's startup flow. For more information about the Activate method, refer to the activateGranify article.
Copy Code
Code
Granify.activateGranify(config)

Set up the Group Assignment event handler

In this step, you will register an event handler that is triggered every time a shopper is assigned a group and then send the group assignment directly to your analytics platform without any modifications.

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 every 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 the subscribeGroupAssigned article.
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 their documentation to determine which method or API call they use to track events.
2. Within your callback function, insert the code that will forward 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 methods that will enable 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 shoppers successfully place which is essential for measuring Contextual Commerce performance

Track page views

The Contextual Commerce SDK cannot automatically detect in-app page changes. Track the active page to ensure Contextual Commerce can show 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
A screen is presented to the user, on any navigation path change

Note: Any modifications to your Activity's Window.Callback must be made before calling trackPageView, or Contextual Commerce won't capture touch events.

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

pageIdentifier: The type of page being viewed and its unique path
activity: Your current FragmentActivity, required for displaying campaign fragments and capturing touch events
navigator: An implementation of the Navigator that the SDK uses to invoke in-app navigation
safeArea : A main-thread closure returning SliderMargins to define a safe slider rendering area that automatically updates during orientation or activity changes to prevent UI obstruction
scrollableView: The scrollable area that shows what part of the page the shopper is viewing, if using a views-based UI
pageRestrictionState : A RestrictionState indicating whether or not the page is eligible to have a slider displayed on it. This parameter is not required, and defaults to UNRESTRICTED

Contextual commerce recognizes the following types of pages:

home: The home page of the app.
product: A page that represents a single product that 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, but allows for the 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, allows 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 that is 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.

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

Copy Code

Code

Granify.trackPageView(
PageIdentifier(PageType.BLOG, "blog"),
this,
ActivityNavigator(this),
{ this.getSafeArea() }
ScrollableView,
pageRestrictionState
)

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 so that every order event is forwarded.

Determine all the 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 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

To learn more about optional parameters, refer to the Product topic.

For more information about tracking orders, refer to the trackOrder article.

The following is an example of the trackOrder method:

Copy Code

Code

Granify.trackOrder(Order(
    orderNumber = "order123",
    lineItemsTotal = Price(250.00),
    subtotal = Price(250.00),
    totalTax = Price(20.00),
    totalShipping = Price(20.00),
    total = Price(290.00),
   lineItems = hashMapOf(
        Product(
            sku = "SKU123",
            productId = "product1",
            title = "Running Shoes",
            price = Price(50.00),
            regularPrice = Price(50.00),
            image = URL("https://example.com/images/shoes"),
            category = "Apparel"
        ) to 1,
        Product(
            sku = "SKU234",
            productId = "product2",
            title = "Headphones",
            price = Price(40.00),
            regularPrice = Price(40.00),
            image = URL("https://example.com/images/headphones"),
            category = "Electronics"
        ) to 1,
        Product(
            sku = "SKU456",
            productId = "product3",
            title = "Water Bottle",
            price = Price(10.00),
            regularPrice = Price(20.00),
            image = URL("https://example.com/images/bottle"),
            category = "Accessories"
        ) to 1
     ),
    discountCodes = emptyList(),
     currency = Currency.USD
))

Prepare the SDK for data validation (Android)

Install the SDK

Configure your project's repository

Add the Granify SDK dependency

Sync your project

Activate the SDK

Collect required information

Create a configuration object

Call the Activate method

Set up the Group Assignment event handler

Subscribe to Group Assigned event

Forward group assignment data to your analytics

Implement basic tracking functionality

Track page views

Track orders