Sending ECommerce events on iOS

In AppMetrica, it is not possible to segment E-commerce events into test and not test. If you use the main API key for debugging purchases, the test events are included in general statistics. Therefore, to debug Ecommerce event sending, use a reporter to send statistics to the additional API key. To learn more about reporters, see Usage examples.

Step 1. Create a test app in AppMetrica

Specify the app parameters: link in the app store (if the app isn't published yet, leave the field empty), name, category, and time zone for generating reports.

To add another app, click Add app in the drop-down list in AppMetrica.

Step 2. Configure sending e-commerce events to the test API key

For different user actions, there are appropriate types of e-commerce events. To create a specific event type, use the appropriate ECommerce class method.

The examples below show how to send specific types of events.

Opening a page
// Creating a screen object.
AMAECommerceScreen *screen = [[AMAECommerceScreen alloc] initWithName:@"ProductCardScreen"
                                                   categoryComponents:@[ @"Promos", @"Hot Deal" ]
                                                          searchQuery:@"danissimo maple syrup"
                                                              payload:@{ @"full_screen": @"true" }];// Sending an e-commerce event.
id<AMAAppMetricaReporting> reporter = [AMAAppMetrica reporterForAPIKey:@"Testing API key"];
[reporter reportECommerce:[AMAECommerce showScreenEventWithScreen:screen] onFailure:nil];
Viewing a product card
// Creating a screen object.
AMAECommerceScreen *screen = [[AMAECommerceScreen alloc] initWithName:@"ProductCardScreen"
                                                   categoryComponents:@[ @"Promos", @"Hot Deal" ]
                                                          searchQuery:@"danissimo maple syrup"
                                                              payload:@{ @"full_screen": @"true" }];// Creating an actualPrice object.
AMAECommerceAmount *actualFiat =
        [[AMAECommerceAmount alloc] initWithUnit:@"USD" value:[NSDecimalNumber decimalNumberWithString:@"4.53"]];
AMAECommerceAmount *woodActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"wood" value:[NSDecimalNumber decimalNumberWithString:@"30570000"]];
AMAECommerceAmount *ironActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"iron" value:[NSDecimalNumber decimalNumberWithString:@"26.89"]];
AMAECommerceAmount *goldActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"gold" value:[NSDecimalNumber decimalNumberWithString:@"5.1"]];
AMAECommercePrice *actualPrice = [[AMAECommercePrice alloc] initWithFiat:actualFiat
                                                      internalComponents:@[ woodActualPrice, ironActualPrice, goldActualPrice ]];// Creating an originalPrice object.
AMAECommerceAmount *originalFiat =
        [[AMAECommerceAmount alloc] initWithUnit:@"USD" value:[NSDecimalNumber decimalNumberWithString:@"5.78"]];
AMAECommerceAmount *woodOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"wood" value:[NSDecimalNumber decimalNumberWithString:@"30590000"]];
AMAECommerceAmount *ironOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"iron" value:[NSDecimalNumber decimalNumberWithString:@"26.92"]];
AMAECommerceAmount *goldOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"gold" value:[NSDecimalNumber decimalNumberWithString:@"5.5"]];
AMAECommercePrice *originalPrice = [[AMAECommercePrice alloc] initWithFiat:originalFiat
                                                        internalComponents:@[ woodOriginalPrice, ironOriginalPrice, goldOriginalPrice ]];// Creating a product object.
AMAECommerceProduct *product = [[AMAECommerceProduct alloc] initWithSKU:@"779213"
                                                                   name:@"Danissimo curd product 5.9%, 130 g"
                                                     categoryComponents:@[ @"Groceries", @"Dairy", @"Yogurts" ]
                                                                payload:@{ @"full_screen" : @"true" }
                                                            actualPrice:actualPrice
                                                          originalPrice:originalPrice
                                                             promoCodes:@[ @"BT79IYX", @"UT5412EP" ]];// Sending an e-commerce event.
id<AMAAppMetricaReporting> reporter = [AMAAppMetrica reporterForAPIKey:@"Testing API key"];
[reporter reportECommerce:[AMAECommerce showProductCardEventWithProduct:product screen:screen] onFailure:nil];
Viewing a product page
// Creating a screen object.
AMAECommerceScreen *screen = [[AMAECommerceScreen alloc] initWithName:@"ProductCardScreen"
                                                   categoryComponents:@[ @"Promos", @"Hot Deal" ]
                                                          searchQuery:@"danissimo maple syrup"
                                                              payload:@{ @"full_screen": @"true" }];// Creating an actualPrice object.
AMAECommerceAmount *actualFiat =
        [[AMAECommerceAmount alloc] initWithUnit:@"USD" value:[NSDecimalNumber decimalNumberWithString:@"4.53"]];
AMAECommerceAmount *woodActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"wood" value:[NSDecimalNumber decimalNumberWithString:@"30570000"]];
AMAECommerceAmount *ironActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"iron" value:[NSDecimalNumber decimalNumberWithString:@"26.89"]];
AMAECommerceAmount *goldActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"gold" value:[NSDecimalNumber decimalNumberWithString:@"5.1"]];
AMAECommercePrice *actualPrice = [[AMAECommercePrice alloc] initWithFiat:actualFiat
                                                      internalComponents:@[ woodActualPrice, ironActualPrice, goldActualPrice ]];// Creating an originalPrice object.
AMAECommerceAmount *originalFiat =
        [[AMAECommerceAmount alloc] initWithUnit:@"USD" value:[NSDecimalNumber decimalNumberWithString:@"5.78"]];
AMAECommerceAmount *woodOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"wood" value:[NSDecimalNumber decimalNumberWithString:@"30590000"]];
AMAECommerceAmount *ironOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"iron" value:[NSDecimalNumber decimalNumberWithString:@"26.92"]];
AMAECommerceAmount *goldOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"gold" value:[NSDecimalNumber decimalNumberWithString:@"5.5"]];
AMAECommercePrice *originalPrice = [[AMAECommercePrice alloc] initWithFiat:originalFiat
                                                        internalComponents:@[ woodOriginalPrice, ironOriginalPrice, goldOriginalPrice ]];// Creating a product object.
AMAECommerceProduct *product = [[AMAECommerceProduct alloc] initWithSKU:@"779213"
                                                                   name:@"Danissimo curd product 5.9%, 130 g"
                                                     categoryComponents:@[ @"Groceries", @"Dairy products", @"Yogurts" ]
                                                                payload:@{ @"full_screen" : @"true" }
                                                            actualPrice:actualPrice
                                                          originalPrice:originalPrice
                                                             promoCodes:@[ @"BT79IYX", @"UT5412EP" ]];// Creating a referrer object.
AMAECommerceReferrer *referrer = [[AMAECommerceReferrer alloc] initWithType:@"button"
                                                                 identifier:@"76890"
                                                                     screen:screen];// Sending an e-commerce event.
id<AMAAppMetricaReporting> reporter = [AMAAppMetrica reporterForAPIKey:@"Testing API key"];
[reporter reportECommerce:[AMAECommerce showProductDetailsEventWithProduct:product referrer:referrer] onFailure:nil];
Adding or removing an item to/from the cart
// Creating a screen object.
AMAECommerceScreen *screen = [[AMAECommerceScreen alloc] initWithName:@"ProductCardScreen"
                                                   categoryComponents:@[ @"Promos", @"Hot Deal" ]
                                                          searchQuery:@"danissimo maple syrup"
                                                              payload:@{ @"full_screen": @"true" }];// Creating an actualPrice object.
AMAECommerceAmount *actualFiat =
        [[AMAECommerceAmount alloc] initWithUnit:@"USD" value:[NSDecimalNumber decimalNumberWithString:@"4.53"]];
AMAECommerceAmount *woodActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"wood" value:[NSDecimalNumber decimalNumberWithString:@"30570000"]];
AMAECommerceAmount *ironActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"iron" value:[NSDecimalNumber decimalNumberWithString:@"26.89"]];
AMAECommerceAmount *goldActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"gold" value:[NSDecimalNumber decimalNumberWithString:@"5.1"]];
AMAECommercePrice *actualPrice = [[AMAECommercePrice alloc] initWithFiat:actualFiat
                                                      internalComponents:@[ woodActualPrice, ironActualPrice, goldActualPrice ]];// Creating an originalPrice object.
AMAECommerceAmount *originalFiat =
        [[AMAECommerceAmount alloc] initWithUnit:@"USD" value:[NSDecimalNumber decimalNumberWithString:@"5.78"]];
AMAECommerceAmount *woodOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"wood" value:[NSDecimalNumber decimalNumberWithString:@"30590000"]];
AMAECommerceAmount *ironOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"iron" value:[NSDecimalNumber decimalNumberWithString:@"26.92"]];
AMAECommerceAmount *goldOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"gold" value:[NSDecimalNumber decimalNumberWithString:@"5.5"]];
AMAECommercePrice *originalPrice = [[AMAECommercePrice alloc] initWithFiat:originalFiat
                                                        internalComponents:@[ woodOriginalPrice, ironOriginalPrice, goldOriginalPrice ]];// Creating a product object.
AMAECommerceProduct *product = [[AMAECommerceProduct alloc] initWithSKU:@"779213"
                                                                   name:@"Danissimo curd product 5.9%, 130 g"
                                                     categoryComponents:@[ @"Groceries", @"Dairy products", @"Yogurts" ]
                                                                payload:@{ @"full_screen" : @"true" }
                                                            actualPrice:actualPrice
                                                          originalPrice:originalPrice
                                                             promoCodes:@[ @"BT79IYX", @"UT5412EP" ]];// Creating a referrer object.
AMAECommerceReferrer *referrer = [[AMAECommerceReferrer alloc] initWithType:@"button"
                                                                 identifier:@"76890"
                                                                     screen:screen];// Creating a cartItem object.
NSDecimalNumber *quantity = [NSDecimalNumber decimalNumberWithString:@"1"];
AMAECommerceCartItem *addedItems = [[AMAECommerceCartItem alloc] initWithProduct:product
                                                                      referrer:referrer
                                                                      quantity:quantity
                                                                       revenue:actualPrice];// Sending an e-commerce event.
id<AMAAppMetricaReporting> reporter = [AMAAppMetrica reporterForAPIKey:@"Testing API key"];
[reporter reportECommerce:[AMAECommerce addCartItemEvent:addedItems] onFailure:nil];
// Or:
[AMAAppMetricareportECommerce:[AMAECommerce removeCartItemEventWithItem:addedItems] onFailure:nil];
Starting and completing a purchase
// Creating a screen object.
AMAECommerceScreen *screen = [[AMAECommerceScreen alloc] initWithName:@"ProductCardScreen"
                                                   categoryComponents:@[ @"Promos", @"Hot Deal" ]
                                                          searchQuery:@"danissimo maple syrup"
                                                              payload:@{ @"full_screen": @"true" }];// Creating an actualPrice object.
AMAECommerceAmount *actualFiat =
        [[AMAECommerceAmount alloc] initWithUnit:@"USD" value:[NSDecimalNumber decimalNumberWithString:@"4.53"]];
AMAECommerceAmount *woodActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"wood" value:[NSDecimalNumber decimalNumberWithString:@"30570000"]];
AMAECommerceAmount *ironActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"iron" value:[NSDecimalNumber decimalNumberWithString:@"26.89"]];
AMAECommerceAmount *goldActualPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"gold" value:[NSDecimalNumber decimalNumberWithString:@"5.1"]];
AMAECommercePrice *actualPrice = [[AMAECommercePrice alloc] initWithFiat:actualFiat
                                                      internalComponents:@[ woodActualPrice, ironActualPrice, goldActualPrice ]];// Creating an originalPrice object.
AMAECommerceAmount *originalFiat =
        [[AMAECommerceAmount alloc] initWithUnit:@"USD" value:[NSDecimalNumber decimalNumberWithString:@"5.78"]];
AMAECommerceAmount *woodOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"wood" value:[NSDecimalNumber decimalNumberWithString:@"30590000"]];
AMAECommerceAmount *ironOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"iron" value:[NSDecimalNumber decimalNumberWithString:@"26.92"]];
AMAECommerceAmount *goldOriginalPrice =
        [[AMAECommerceAmount alloc] initWithUnit:@"gold" value:[NSDecimalNumber decimalNumberWithString:@"5.5"]];
AMAECommercePrice *originalPrice = [[AMAECommercePrice alloc] initWithFiat:originalFiat
                                                        internalComponents:@[ woodOriginalPrice, ironOriginalPrice, goldOriginalPrice ]];// Creating a product object.
AMAECommerceProduct *product = [[AMAECommerceProduct alloc] initWithSKU:@"779213"
                                                                   name:@"Danissimo curd product 5.9%, 130 g"
                                                     categoryComponents:@[ @"Groceries", @"Dairy products", @"Yogurts" ]
                                                                payload:@{ @"full_screen" : @"true" }
                                                            actualPrice:actualPrice
                                                          originalPrice:originalPrice
                                                             promoCodes:@[ @"BT79IYX", @"UT5412EP" ]];// Creating a referrer object.
AMAECommerceReferrer *referrer = [[AMAECommerceReferrer alloc] initWithType:@"button"
                                                                 identifier:@"76890"
                                                                     screen:screen];// Creating a cartItem object.
NSDecimalNumber *quantity = [NSDecimalNumber decimalNumberWithString:@"1"];
AMAECommerceCartItem *addedItems = [[AMAECommerceCartItem alloc] initWithProduct:product
                                                                      referrer:referrer
                                                                      quantity:quantity
                                                                       revenue:actualPrice];
// Creating an order object.
AMAECommerceOrder *order = [[AMAECommerceOrder alloc] initWithIdentifier:@"88528768"
                                                               cartItems:@[ addedItems ]
                                                                 payload:@{ @"black_friday" : @"true"}];
// Sending an e-commerce event.
id<AMAAppMetricaReporting> reporter = [AMAAppMetrica reporterForAPIKey:@"Testing API key"];
[reporter reportECommerce:[AMAECommerce beginCheckoutEventWithOrder:order] onFailure:nil];
[AMAAppMetricareportECommerce:[AMAECommerce purchaseEventWithOrder:order] onFailure:nil];
Opening a page
// Creating a screen object.
let screen = ECommerceScreen(
        name: "ProductCardScreen",
        categoryComponents: ["Promos", "Hot Deal"],
        searchQuery: "danissimo maple syrup",
        payload: ["full_screen": "true"]
)// Sending an e-commerce event.
AppMetrica.report(eCommerce: .showScreenEvent(screen: screen), onFailure: nil)
Viewing a product card
// Creating a screen object.
let screen = ECommerceScreen(
        name: "ProductCardScreen",
        categoryComponents: ["Promos", "Hot Deal"],
        searchQuery: "danissimo maple syrup",
        payload: ["full_screen": "true"]
)// Creating an actualPrice object.
let actualPrice = ECommercePrice(
        fiat: .init(unit: "USD", value: .init(string: "4.53")),
        internalComponents: [
            .init(unit: "wood", value: .init(string: "30570000")),
            .init(unit: "iron", value: .init(string: "26.89")),
            .init(unit: "gold", value: .init(string: "5.1")),
        ]
)// Creating a product object.
let product = ECommerceProduct(
        sku: "779213",
        name: "Danissimo Curd Dessert 5.9%, 130 g",
        categoryComponents: ["Groceries", "Dairy", "Yogurts"],
        payload: ["full_screen": "true"],
        actualPrice: actualPrice,
        originalPrice: .init(
                fiat: .init(unit: "USD", value: .init(string: "5.78")),
                internalComponents: [
                    .init(unit: "wood", value: .init(string: "30590000")),
                    .init(unit: "iron", value: .init(string: "26.92")),
                    .init(unit: "gold", value: .init(string: "5.5")),
                ]
        ),
        promoCodes: ["BT79IYX", "UT5412EP"]
)// Sending an e-commerce event.
AppMetrica.report(eCommerce: .showProductCardEvent(product: product, screen: screen), onFailure: nil)
Viewing a product page
// Creating a screen object.
let screen = ECommerceScreen(
        name: "ProductCardScreen",
        categoryComponents: ["Promos", "Hot Deal"],
        searchQuery: "danissimo maple syrup",
        payload: ["full_screen": "true"]
)// Creating an actualPrice object.
let actualPrice = ECommercePrice(
        fiat: .init(unit: "USD", value: .init(string: "4.53")),
        internalComponents: [
            .init(unit: "wood", value: .init(string: "30570000")),
            .init(unit: "iron", value: .init(string: "26.89")),
            .init(unit: "gold", value: .init(string: "5.1")),
        ]
)// Creating a product object.
let product = ECommerceProduct(
        sku: "779213",
        name: "Danissimo Curd Dessert 5.9%, 130 g",
        categoryComponents: ["Groceries", "Dairy", "Yogurts"],
        payload: ["full_screen": "true"],
        actualPrice: actualPrice,
        originalPrice: .init(
                fiat: .init(unit: "USD", value: .init(string: "5.78")),
                internalComponents: [
                    .init(unit: "wood", value: .init(string: "30590000")),
                    .init(unit: "iron", value: .init(string: "26.92")),
                    .init(unit: "gold", value: .init(string: "5.5")),
                ]
        ),
        promoCodes: ["BT79IYX", "UT5412EP"]
)// Creating a referrer object.
let referrer = ECommerceReferrer(type: "button", identifier: "76890", screen: screen)// Sending an e-commerce event.
AppMetrica.report(eCommerce: .showProductDetailsEvent(product: product, referrer: referrer), onFailure: nil)
Adding/removing an item to/from the cart
// Creating a screen object.
let screen = ECommerceScreen(
        name: "ProductCardScreen",
        categoryComponents: ["Promos", "Hot Deal"],
        searchQuery: "danissimo maple syrup",
        payload: ["full_screen": "true"]
)// Creating an actualPrice object.
let actualPrice = ECommercePrice(
        fiat: .init(unit: "USD", value: .init(string: "4.53")),
        internalComponents: [
            .init(unit: "wood", value: .init(string: "30570000")),
            .init(unit: "iron", value: .init(string: "26.89")),
            .init(unit: "gold", value: .init(string: "5.1")),
        ]
)// Creating a product object.
let product = ECommerceProduct(
        sku: "779213",
        name: "Danissimo Curd Dessert 5.9%, 130 g",
        categoryComponents: ["Groceries", "Dairy", "Yogurts"],
        payload: ["full_screen": "true"],
        actualPrice: actualPrice,
        originalPrice: .init(
                fiat: .init(unit: "USD", value: .init(string: "5.78")),
                internalComponents: [
                    .init(unit: "wood", value: .init(string: "30590000")),
                    .init(unit: "iron", value: .init(string: "26.92")),
                    .init(unit: "gold", value: .init(string: "5.5")),
                ]
        ),
        promoCodes: ["BT79IYX", "UT5412EP"]
)// Creating a referrer object.
let referrer = ECommerceReferrer(type: "button", identifier: "76890", screen: screen)// Creating a cartItem object.
let addedItems = ECommerceCartItem(
        product: product,
        referrer: referrer,
        quantity: .init(string: "1"),
        revenue: actualPrice
)// Sending an e-commerce event.
AppMetrica.report(eCommerce: .addCartItemEvent(cartItem: addedItems), onFailure: nil)
// Or:
AppMetrica.report(eCommerce: .removeCartItemEvent(cartItem: addedItems), onFailure: nil)
Starting and completing a purchase
// Creating a screen object.
let screen = ECommerceScreen(
        name: "ProductCardScreen",
        categoryComponents: ["Promos", "Hot Deal"],
        searchQuery: "danissimo maple syrup",
        payload: ["full_screen": "true"]
)// Creating an actualPrice object.
let actualPrice = ECommercePrice(
        fiat: .init(unit: "USD", value: .init(string: "4.53")),
        internalComponents: [
            .init(unit: "wood", value: .init(string: "30570000")),
            .init(unit: "iron", value: .init(string: "26.89")),
            .init(unit: "gold", value: .init(string: "5.1")),
        ]
)// Creating a product object.
let product = ECommerceProduct(
        sku: "779213",
        name: "Danissimo Curd Dessert 5.9%, 130 g",
        categoryComponents: ["Groceries", "Dairy", "Yogurts"],
        payload: ["full_screen": "true"],
        actualPrice: actualPrice,
        originalPrice: .init(
                fiat: .init(unit: "USD", value: .init(string: "5.78")),
                internalComponents: [
                    .init(unit: "wood", value: .init(string: "30590000")),
                    .init(unit: "iron", value: .init(string: "26.92")),
                    .init(unit: "gold", value: .init(string: "5.5")),
                ]
        ),
        promoCodes: ["BT79IYX", "UT5412EP"]
)// Creating a referrer object.
let referrer = ECommerceReferrer(type: "button", identifier: "76890", screen: screen)// Creating a cartItem object.
let addedItems = ECommerceCartItem(
        product: product,
        referrer: referrer,
        quantity: .init(string: "1"),
        revenue: actualPrice
)
// Creating an order object.
let order = ECommerceOrder(
        identifier: "88528768",
        cartItems: [addedItems],
        payload: ["black_friday": "true"]
)
// Sending an e-commerce event.
AppMetrica.report(eCommerce: .beginCheckoutEvent(order:order), onFailure: nil)
AppMetrica.report(eCommerce: .purchaseEvent(order: order), onFailure: nil)

Step 3. Check the test application's report

Make in-app test purchases. After a while, check the Purchase analysis report in the AppMetrica interface. Make sure that the report shows e-commerce events.

To learn more about these reports, see Purchase analysis.

Step 4. Configure sending ECommerce to the main API Key

After successful testing, configure sending E-commerce events to the main API key.

To send the ECommerce instance to the main API key, use the +reportECommerce:onFailure: method of the AppMetrica class.

// ...
// Sending an e-commerce event.
[AMAAppMetricareportECommerce:[ECommerce showScreenEventWithScreen:screen] onFailure:nil];
// ...
// Sending an e-commerce event.
AppMetrica.report(eCommerce: .showScreenEvent(screen: screen), onFailure: nil)

If you didn't find the answer you were looking for, you can use the feedback form to submit your question. Please describe the problem in as much detail as possible. Attach a screenshot if possible.

Contact support