Track From App

CartEvent#

There events indicate user interactions with cart

Add product to cart

Android
iOS

terraTracker.getInstance().trackCartEvent(
    CartEventIdentifier.CartEventName.AddToCart,
    CartEventBody(
        skuId = "1234567", // product's sku
        skuName = "Product name", // product's name
        price = 1000000, // product's original price
        promotionPrice = 999000, // product's price after discount
        quantity = 1,  // product's quantity in cart after added
        status = EventConstants.Status.Success, // if the action is success
        promotionId = "123", // id of the promotion associated with this product, optional
        coupon = "ABCD", // coupon associated with this product, optional
        cartId = "cart-id-1" // id of the cart, optional
    )
)

Remove product from cart

Android
iOS

terraTracker.getInstance().trackCartEvent(
    CartEventIdentifier.CartEventName.RemoveFromCart,
    CartEventBody(
        skuId = "1234567", // product's sku
        skuName = "Product name", // product's name
        price = 1000000, // product's original price
        promotionPrice = 999000, // product's price after discount
        quantity = 1,  // product's quantity in cart after remove
        status = EventConstants.Status.Success, // if the action is success
        promotionId = "123", // id of the promotion associated with this product, optional
        coupon = "ABCD", // coupon associated with this product, optional
        cartId = "cart-id-1" // id of the cart, optional
    )
)

Increase quantity product

Track when press + button to quickly increase quantity in cart
According constant CartEventIdentifier.CartEventName.IncreaseQuantityProduct

Decrease quantity product

Track when press - button to quickly decrease quantity in cart
According constant CartEventIdentifier.CartEventName.DecreaseQuantityProduct

Select product

Track when user tick checkbox to mark product as selected for checkout in cart
According constant CartEventIdentifier.CartEventName.SelectProduct

Deselect product

Track when user un-tick checkbox to mark product as not selected for checkout in cart
According constant CartEventIdentifier.CartEventName.UnSelectProduct

Revert product

Track when user revert the "remove product from cart" action
According constant CartEventIdentifier.CartEventName.RevertProductToCart

ScreenViewEvent#

There events indicate user view/exit a screen in your app.

Android
iOS

// Firstly, define your app screen enum like this
enum class AppScreenName(override val value: String) : ScreenName {
    HomePage("homePage"),
    Cart("cart"),
    ProductList("productList")
}

// Also, define your app screen content type enum like this
enum class AppContentType(override val value: String) : ContentType {
    Home("home"),
    Discovery("discovery"),
    CheckOut("checkOut")
}

// In your activity/fragment, implement interface TrackableScreen to enable auto-tracking mechanism
// this interface will provide information about current screen
class MainActivity(): TrackableScreen {
    override fun shouldTrack(): Boolean { return true/false  } // this screen should be tracked or not
    override fun screenName(): ScreenViewEventBody.ScreenName // name of this screen if shouldTrack return true
    override fun contentType(): ScreenViewEventBody.ContentType // content of this screen if shouldTrack return true
    override fun referrerScreen(): ScreenViewEventBody.ScreenName? = null // which screen is navigating to this screen
    override fun skuId(): String? = null // optional, if this screen is showing product detail, then pass the product sku
    override fun skuName(): String? = null // optional, if this screen is showing product detail, then pass the product name
    override fun sdkId(): String? = null // optional, if you use Tracker inside your library, return your library identifier
    override fun sdkVersion(): String? = null // optional, if you use Tracker inside your library, return your library version
}

// Because Tracker support multiple instance, so you also need to implement interface AppIdentifier
// and return the AppName you used to initialize your Tracker. This interface help Tracker recognize its event.
class MainActivity(): TrackableScreen, AppIdentifier {
    override val appIdentifier: String? = "app_name"
}

// if you use only fragment, do the same as above for your fragment

Detail documentation for each method, please go to see release notes for version 1.0.0

Track raw event (not recommended):
In case you want to manually track the ScreenViewEvent, use this function

terraTracker.getInstance().trackScreenViewEvent(
    eventName = ScreenViewEventIdentifier.ScreenViewEventName.EnterScreenView, // enter or exit screen
    body = ScreenViewEventBody(
        screenName = AppScreenName.HomePage, // new screen just displayed to user
        referrer = AppScreenName.Cart, // the screen before we enter this screen
        contentType = AppContentType.HomePage, // screen type, somewhat the group that this screen belongs to
        skuId = "1234567", // optional, if this screen is showing product detail, then pass the product sku
        skuName = "Product Name", // optional, if this screen is showing product detail, then pass the product name
        navigationStart = 1234567890, // timestamp when start navigation
        loadEventEnd = 1234567899 // timestamp when page load ends
    )
)

Simply set trackingName, trackingContentType for the ViewController in swift code or in Xib file. You need to set both of those properties to track screen view event.

Example:

class ViewController {

    func viewDidLoad() {
        super.viewDidLoad()

        trackingName = "<screen_tracking_name>"
        trackingContentType = "content-type"
    }

}

TerraTracker will automatically track this ViewController visible event.

VisibleContentEvent#

There events indicate which contents are showing to user.

Android
iOS

// visibleProducts is a list of products that are currently showing on screen
terraTracker.getInstance().trackVisibleContentEvent(
    visibleProducts.map { idx ->
        VisibleContentEventBody(
            regionName = "Product List",
            // region of this content, for example in home screen your app has both "Product List" and "Promotion List"
            // so this will indicate which section we are referring to
            index = idx, // index of the content
            contentName = product.sku // sku of the product
        )
    }
)

RecyclerView support to auto-detect visible items and track when user scroll list:

// rcvProducts is the RecyclerView showing list of products
// products is the data list of product that backing this recycler view
val listener =
    RecyclerViewTrackingListener(
        AppRegionName.ProductList,
        // this is a RegionName enum, you can create your own AppRegionName like AppScreenName as described
        // in Screen View section above
        object : ItemTrackingInfoExtractor {
            // return an empty string ("") if you don't want to track for a specific item in the list
            override fun getContentName(position: Int): String {
                return products[position].sku // return the sku of product in this position
            }
        }
    )
rcvProducts.addOnScrollListener(listener)

// remember to clear and remove this listener when your view is destroyed
listener.clear()
rcvProducts.removeOnScrollListener(listener)

Simply set trackingRegionName and trackingContentName for the UIView

Example:

func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(withIdentifier: "Cell", for: indexPath)

    cell.textLabel?.text = "Scroll to track visible content event" + String(describing: indexPath)
    cell.trackingRegionName = "cell-region-name"
    cell.trackingContentName = "cell-content-name"
    return cell
}

InteractionContentEvent#

These events indicate user interactions with app, like clicking on buttons.

Firstly, define your app region, content and target like this:

Android
iOS

Firstly, define the region/content/target in your app like this

enum class AppRegionName(override val value: String) : RegionName {
    BtnChangeProductPromotion("btnChangeProductPromotion"),
    ScanCodeTabMenu("scanCodeTabMenu"),
    HeaderScanScreen("headerScanScreen")
}

enum class AppContentName(override val value: String) : ContentName {
    SelectProductPromotion("selectProductPromotion"),
    SwitchScanCodeType("switchScanCodeType"),
    SearchProductByKeyword("searchProductByKeyword")
}

enum class AppTarget(override val value: String) : Target {
    SelectProductPromotion("selectProductPromotion"),
    ProductDetail("productDetail"),
    ShoppingCart("shoppingCart")
}

Then track the event when the button is clicked with this code

terraTracker.getInstance().trackInteraction(
    InteractionContentEventBody(
        regionName = AppRegionName.BtnChangeProductPromotion, // region name
        contentName = AppContentName.SelectProductPromotion, // content name
        target = AppScreenName.SelectProductPromotion, // target
        payload = StringUtil.buildFromObject(mapOf( // payload is a stringify custom object
           "sku" to product.sku,
           "index" to idx
        )),
        interaction = InteractionContentEventBody.Interaction.Click
    )
)

Firstly, define the region/content/target in your app like this

enum InteractionRegionName: String {
    // Product
    case interestedProduct
    case topPromotion
    case allProduct
    // Cart
    case headerShoppingCart
    case bottomShoppingCart
    case couponSection
    case promotionOfSeller
}

enum InteractionContentName: String {
    case checkout
    case closeCart
    case createOrder
    case openCouponPopup
    case removeCoupon
    case revertCoupon
}

enum ScreenTrackingName: String {
    case productDetail
    case productRelated
    case promotionDetail
    case promotionViewBenefit
}

tracker?.sendInteractionContentEvent(data: .init(regionName: InteractionRegionName.topPromotion,
                                                contentName: InteractionContentName.createOrder,
                                                target: ScreenTrackingName.promotionDetail,
                                                payload: [String: Any](),
                                                relativePosition: relativePosition,
                                                absolutePosition: absolutePosition)

On the other hand, we can track tap action automatically by set trackingRegionName, trackingContentName, trackingPayload, trackingTarget for the UIView you want to track. You need to set enough 4 properties for track that view.

Example:

confirmButton.trackingRegionName = "cell-region-name"
confirmButton.trackingContentName = "cell-content-name"
confirmButton.trackingPayload = [:]
confirmButton.trackingTarget = "cell-tracking-target"

AlertEvent#

These events indicate that an popup message is showing, require user click to dismiss or make decision.

Android
iOS

terraTracker.getInstance().trackAlertEvent(
    AlertEventBody(
        alertType = AlertEventBody.AlertType.Popup, // Popup and Toast are available
        alertMessage = "warning products out of stock" // message showing in the popup
    )
)

tracker?.sendAlertEvent(data: .init(alertType: alertType.rawValue,
                                    alertMessage: alertMessage,
                                    sdkID: "your-sdk-id",
                                    sdkVersion: "your-sdk-version"))

With default UIAlertController, we only need to set these values then it will be tracked automatically when being presented.

alert.trackingSdkId = TrackingCommonProperties.sdkID
alert.trackingSdkVersion = TrackingCommonProperties.sdkVersion
alert.trackingAlertMessage = message.orEmpty
alert.shouldTrackAsAlert = true

For Kotlin

ErrorEvent#

These events indicate that network exceptions have occurred.

Android
iOS

The library provides an ErrorTrackingInterceptor that can be used with OkHttp:

Add this interceptor when you build your OkHttp client. For Kotlin:

OkHttpClient.Builder()
        .addInterceptor(ErrorTrackingInterceptor())
        .build()

The library by default will read field code and message from the http response when http status is not success. If your server return different format, please override ErrorTrackingInterceptor class with two functions:

getErrorCodeAndMessage return a Pair<String, String> to indicate error code and error message, called when the http request is failed (non 2xx status)
getCustomErrorCodeAndMessage return a Pair<String, String> to indicate error code and error message, called when the http request is success (2xx status)

This will help the interceptor to correctly parse your failure code and message from server response.

To track the ErrorEvent on your own, use:

terraTracker.getInstance().trackErrorEvent(
    ErrorEventBody(
        errorSource = ErrorEventBody.ErrorSource.Http, // error source type
        apiCall = "your_request_url", // the request url
        apiPayload = "body_payload", // the request payload
        httpResponseCode = "200", // http response code, optional
        responseJson = "response_body", // http response body, optional
        errorCode = "123", // error code returned by your server
        errorMessage = "200 but error" // error message returned by your server
    )
)

Http error events will be tracked automatically. You can add URLs to BLACKLIST_URL and WHITELIST_URL in the TekoTracker-Info.plist file to ignore or specify trackable urls.

If the whitelist is empty, all the urls that not included in the blacklist will be tracked.

URL values must start with http or https.

NOTE

If you want to track error response of an SDK, each API request must be added these value to headers

"TERRA_TRACKING_SDK_ID": "<YOUR_SDK_ID>",
"TERRA_TRACKING_SDK_VERSION": "<YOUR_SDK_VERSION>"

ExceptionEvent#

Android
iOS

The library automatically tracks this event

Add this line into the body of TerraApp.configure closure.

Tracker.catchException()

SearchEvent#

These events indicate the search action of user

Android
iOS

terraTracker.getInstance().trackSiteSearchEvent(
    SiteSearchEventBody(
        params = StringUtil.buildFromObject(mapOf(
            "q" to "laptop",
            "price_gte" to 10000000,
            "publish" to true
        )), // your query params, stringify
        keywords = "laptop", // searching keyword
        sort = "newest", // sorting param, optional
        order = "asc" // sort order, optional
    )
)

For Kotlin

PaymentEvent#

These events indicate the user action related to payment

Android
iOS

terraTracker.getInstance().trackPaymentEvent(
    PaymentEventBody(
        orderId = "123123-1231231-2131", // orderId returned by OrderManagement service
        amount = 10000000L, // order total value
        paymentMethod = PaymentEventBody.PaymentMethod.Cash, // payment method
        status = EventConstants.Status.Success, // indicate success payment, can be Success/Failed/Timeout
        statusCode = 1000 // the payment code returned by Payment service
    ).apply {
        attr1 = 1000 // the payment code returned by Payment service
        attr5 = StringUtil.buildFromObject(paymentResponse) // the whole response returned by Payment service
    }
)

CheckoutEvent#

These events indicate user checkout the cart

Android
iOS

terraTracker.getInstance().trackCheckoutEvent(
    CheckoutEventBody(
        orderId = "123123-1231231-2131", // orderId returned by OrderManagement service
        amountBeforeDiscount = 10000000, // total value before discount
        amountAfterDiscount = 9000000, // total value after discount
        discountAmount = 1000000, // discount amount
        shippingFee = 0, // shipping fee
        products = items.map {
            CheckoutEventBody.Product(
                price = it.price.toLong(), // product's original price
                promotionPrice = it.promotionPrice.toLong(), // product's promotion price
                quantity = it.quantity.toLong(), // product quantity to buy
                skuId = it.sku, // product sku
                skuName = it.name // product name
            )
        }, // list of products in cart
        status = EventConstants.Status.Success, // indicate success checkout, can be Success/Failed/Timeout
        note = "giao hang nhanh nha" // order note
    )
)

CustomEvent#

Use this event to track anything you need

Android
iOS

terraTracker.getInstance().trackCustomEvent(
        CustomEventBody(
            category = "category", // any string you want
            action = "action", // any string you want
            label = "label", // any string you want
            property = "property", // any string you want
            value = 0 // any Long you want
        ).apply {
            attr1 = "custom property 1" // any string you want
            attr2 = "custom property 2" // any string you want
            attr3 = "custom property 3" // any string you want
            attr4 = "custom property 4" // any string you want
            attr5 = "custom property 5" // any string you want
        }
    )

UTM Data#

We provide a way to track the utm data in the url where the app open from, includes: utm_source, utm_campaign, utm_term, utm_medium, utm_content.

Android
iOS

Add this line to your application's Activities

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    terraTracker.getInstance().onNewIntent(this, intent)
}

Add this line to the handle function when your app open from any url.

Tracker.application(app, open: url)

In our case, we need to add to these function in the AppDelegate:

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

}

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                     restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
}

func setupTerra() {
    TerraApp.configure { success, terraApp in
        TerraTracker.configure(app: terraApp) 

        // After configure TerraTracker
        if appOpenFromUrl {
            Tracker.application(app, open: url)
        }
    }
}