Implement inline campaigns (iOS)

The Contextual Commerce SDK supports display of inline campaigns. Inline campaigns display via views embedded in your application’s user interface. The following image shows an example inline campaign. 

The Contextual Commerce SDK supports both UIKit and SwiftUI. Refer to the relevant section for your implementation:

• UIKit implementation 
• SwiftUI implementation 

UIKit implementation

Step 1: Add the parentView parameter

1. Update your Granify.trackPageView(...) calls.
2. Add the parentView parameter. This must be a superview containing all the subviews on the current page. We require this view to locate all the GranifyInlineView on the page.

Step 2: Add the view to the layout

1. Add a GranifyInlineView object to every position on the page where an inline campaign is desired.
2. Ensure the view is initially hidden by setting the height constraint to 0.
3. If using Interface Builder, set the top constraint to the view above and the bottom constraint to the view below.

The following are recommended constraints if you are using interface builder and storyboards:

• Height constraint of 0
• Top of the GranifyInlineViewconstrained to the bottom of the view above 
• Bottom of the GranifyInlineView constrained to the top of the view below

Note:  If adding the view to a UIStackView, only the height constraint of 0 is needed.

Step 3: Configure expand and collapse handlers

1. Create an expand handler using GranifyInlineViewExpander to adjust height when a campaign is available.
2. Create a collapse handler using GranifyInlineViewCollapser to return the view to 0 height.
3. Pass these handlers to the view using setExpandHandler and setCollapseHandler inside viewDidLoad() of the current view controller.

Note: The Contextual Commerce SDK handles inline animation internally. Do not add additional animation handling. 

If you create a GranifyInlineView programmatically, you can pass these handlers during initialization. Use the following handlers if you used the preceding recommended constraints:

extension UIView {
    var heightConstraint: NSLayoutConstraint? {
        return constraints.first(where: {
            $0.firstAttribute == .height && $0.relation == .equal
        })
    }

    // expand handler (pass into `GranifyInlineView.setExpandHandler(expandHandler:)`)
    func expandZeroHeightConstraint(toHeight: CGFloat) {
        self.heightConstraint?.constant = toHeight
        self.frame = CGRect(x: self.frame.minX, y: self.frame.minY, width: self.frame.width, height: toHeight)
    }

    // collapse handler (pass into `GranifyInlineView.setCollapseHandler(collapseHandler:)`
    func collapseZeroHeightConstraint() {
        self.heightConstraint?.constant = 0
        self.frame = CGRect(x: self.frame.minX, y: self.frame.minY, width: self.frame.width, height: 0)
    }
}

Step 4: Initialize the label

1. Initialize the GranifyInlineViewLabel parameter.
2. Assign a name string to the label using GranifyInlineView.setLabel(label:).

A GranifyInlineViewLabel has three fields:

• name: Required. Identifies the associated GranifyInlineView. This must be unique per location on a parent view unless a productId is provided to differentiate items. 
• productId: Required if the view is associated with a specific product (such as on a product page or a specific item in a cart).
• sku: Required if the associated productId has multiple SKUs. 

Provide a list of names used in GranifyInlineViewLabel to your Contextual Commerce account manager to enable campaign creation for those labels.

Note: If you use a dynamic view (such as UITableView or UICollectionView), you must reapply the label whenever the view content updates to reflect the new content (such as productId or sku).

SwiftUI implementation

To enable inline campaigns in a SwiftUI application, you must add at least one GranifyInlineSwiftUIView to your page. The SDK handles the expanding, collapsing, and animation of these views automatically.

Step 1: Add the view to the layout

1. Insert the GranifyInlineSwiftUIView into your View hierarchy at every position where an inline campaign is desired.  
2. Provide the constructor with a GranifyInlineViewLabel.

Caution: Do not place the view on the root level of a ZStack as this may cause overlap issues. The view maintains a minimum height of 0.1pt when collapsed to ensure stability in LazyVStack. 

Step 2: Configure product details

• name: Required. Identifies the associated view and must be unique per location within a SwiftUI View 

Note: If the same name is used on multiple views (for example, in a cart list), they must be differentiated by productId and sku. 

• productId: Required when the view is on a product page or associated with a specific product (for example, inlines tied to a cart product)
• sku: Required when the view is associated with a specific productID and SKU combination.

Product pages:

1. Set the productId field. This is required for any inline campaign located on a Product Page.
2. Set the name to be unique for that location.

struct SampleSwiftUIView: View {
    var body: some View {
        VStack {
            Text("Product Title")
            GranifyInlineSwiftUIView(label: GranifyInlineViewLabel(
                name: "belowProductTitle",
                productId: "\(product.id)"
            ))
            Image("Product Image")
            Text("Product Description")
        }
    }
}

Cart pages:

1. Set the productId for any inline tied to a specific item. Include the sku if the product has multiple variants.
2. Use only the name field for areas not tied to a specific product (for example, top of the page).

struct SampleSwiftUIView: View {
    var body: some View {
        VStack {
            Text("Cart Items")
            GranifyInlineSwiftUIView(label: GranifyInlineViewLabel(
                name: "aboveCartItemList"
            ))
            List(Cart.items) { cartItem in
                VStack {
                    Text("\(cartItem.title)")
                    GranifyInlineSwiftUIView(label: GranifyInlineViewLabel(
                        name: "belowCartItemTitle",
                        productId: "\(cartItem.productId)",
                        sku: "\(cartItem.sku)"
                    ))
                    Text("Quantity: \(cartItem.quantity)")
                }
            }
        }
    }
}
Testing

Step 3: Finalize integration

1. Compile a list of all name values used in your labels.
2. Send this list to your Contextual Commerce account manager to create the campaigns.

Caution: Do not change these label names after this point without notifying your Contextual Commerce account manager, as doing so will break live campaigns.