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.

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).

Customize click behaviors for shopping

Please refer to 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.

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) {
        // 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)
                
                // 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.

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"
    ]
)