# Shopping (iOS)

FireworkVideoSDK contains a `shopping` property that enables video shopping integration. There are two main points of integration both located on the `FireworkVideoShopping` type.

### **FireworkVideoShoppingDelegate**

Assign `FireworkVideoShoppingDelegate` delegate to receive important shopping events.

```swift
FireworkVideoSDK.shopping.delegate = <Your delegate>
```

The shopping lifecycle events provide opportinities to customize the product views, hydrate product information and handle when a user adds a product variant to the cart.

### Shopping configurations

Please refer to [Shopping configurations (iOS)](/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/customization-ios/shopping-configurations-ios.md).

### **Customize** click behaviors for shopping

Please refer to [Customize click behaviors for shopping](https://docs.firework.com/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/customization-ios/customize-click-behaviors-ios#customize-click-behaviors-for-shopping).

### **Global Product Hydration**

The `fireworkShopping(_:updateDetailsForProducts:forVideo:_:)` method will be called when a video will be shown that contains products. It is at this point when the host app will be able to update the associated product information. In `fireworkShopping(_:updateDetailsForProducts:forVideo:_:)`, you could use `ProductHydrating` API to hydrate products. For example, you could update product names, descriptions, and variants.

```swift
func fireworkShopping(
    _ fireworkShopping: FireworkVideoShopping,
    updateDetailsForProducts products: [ProductID],
    forVideo video: VideoDetails,
    _ productHydrator: any ProductHydrating) {
    // Retrieve the most up-to-date product details
    // based on the product IDs from the host app server

    // Introduce a delay to mimic a network request that fetches
    // updated product data after the hydration callback is triggered.
    DispatchQueue.global().asyncAfter(wallDeadline: .now() + 3) {
        // Get product model list
        let productModels = productHydrator.products
        // Call hydration API
        for productID in products {
            productHydrator.hydrateProduct(productID) { productBuilder in
                // Update product info
                productBuilder
                    .name("Latest product name")
                    .description("Latest product description")
                    .isAvailable(true)

                // Set to true to hide the product, or false to keep it visible
                productBuilder.hidden(true)
                
                // Update product variants.
                // The strategy can be merge or replace.
                // With merge strategy, we will merge these new variants into existing variants. We use variant id to match the variant.
                // With `replace` strategy, we will replace existing variants with these new variants.
                productBuilder.variants(.merge) { variantsBuilder in
                    // Build variant
                    variantsBuilder.variant("variant id1") { variantBuilder in
                        variantBuilder.formattedPrice(100, currencyCode: "USD")
                            .formattedOriginalPrice(120, currencyCode: "USD")
                            .url("Latest variant url1")
                            .imageUrl("Latest variant image url1")
                            .isAvailable(true)
                            .options([
                                "Color": "Latest variant color1",
                                "Size": "Latest variant size1"
                            ])
                        return variantBuilder
                    }
                    
                    // Build variant
                    variantsBuilder.variant("variant id2") { variantBuilder in
                        variantBuilder.name("Latest variant name2")
                            .formattedPrice(110, currencyCode: "USD")
                            .formattedOriginalPrice(130, currencyCode: "USD")
                            .url("Latest variant url2")
                            .imageUrl("Latest variant image url2")
                            .isAvailable(true)
                            .options([
                                "Color": "Latest variant color2",
                                "Size": "Latest variant size2"
                            ])
                        return variantBuilder
                    }
                    return variantsBuilder
                }
                return productBuilder
            }
        }
    }
}
```

**Strategy for hydrating product variants**

1. With `merge` strategy, we will merge these new variants into existing variants. We use variant id to match the variant.
2. With `replace` strategy, we will replace existing variants with these new variants.

### Purchase tracking

The host app can record a purchase which will help get a full picture of the user journey flow\.In order to do this, call `FireworkVideoSDK.trackPurchase` whenever the purchase happens.

```swift
let value: Double = // The total value of the purchase
let shippingPrice: Double = // The shipping price
let subtotal: Doublie = //Subtotal, without shipping price. Usually, value = shippingPrice + subtotal
let products: [PurchaseProduct] = [
    PurchaseProduct(
        extProductID: // External product id
        price: // Product price
        quantity: // Quantity
    )
]
FireworkVideoSDK.trackPurchase(
    orderID: "<Order ID of User Purchase>",
    value: value,
    currencyCode: Locale.current.currencyCode,
    countryCode: Locale.current.regionCode,
    shippingPrice: shippingPrice,
    subtotal: subtotal,
    products: products,
    /// Any additional information associated to the purchase.
    /// Reserved keys: order_id, value, currency, country, shipping_price, subtotal, product.
    /// Any values passed in the additionalInfo that use a reserved key will be ignored.
    [
        "additionalKey1": "additionalValue1",
        "additionalKey2": "additionalValue2",
        "additionalKey3": "additionalValue3"
    ]
)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.firework.com/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/shopping-ios.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.