Appearance

Analytics ​

Core Events ​

This document provides an overview of the analytics events used across all Hubtel mobile applications. These events are critical for tracking user interactions, system processes, and app performance, enabling the team to make data-driven decisions to enhance user experience and app functionality.

Authentication Events ​

  • login ("login"): Triggered when a user successfully logs into the app.
  • requestAuthChallenge ("request_otp"): Occurs when a user requests a One-Time Password (OTP) for authentication purposes.
  • authValidationFailed ("otp_validation_failed"): Fired when an OTP validation attempt fails.

Session Events ​

  • startSession ("start_session"): Indicates the beginning of a user session within the app.

User Interaction Events ​

  • viewSection ("view_section"): Triggered when a user views a specific section within the app.
  • beginPurchase ("begin_purchase"): Occurs when a user initiates a purchase process.
  • beginCheckout ("begin_checkout"): Fired when a user starts the checkout process.
  • purchase ("purchase"): Indicates a successful purchase transaction.
  • purchaseFailed ("purchase_failed"): Occurs when a purchase transaction fails.
  • view ("view"): Triggered when a user views a page or screen.
  • viewItem ("view_item"): Fired when a user views a specific item's details.
  • search ("search"): Occurs when a user performs a search action.
  • tap ("tap"): Indicates a tap action by the user on the app's interface.
  • report ("report"): Triggered when a user submits a report through the app.
  • share ("share"): Fired when a user shares content from the app.
  • addToCart ("add_to_cart"): Occurs when a user adds an item to their shopping cart.
  • removeFromCart ("remove_from_cart"): Triggered when a user removes an item from their shopping cart.
  • clearCart ("clear_cart"): Indicates when a user clears all items from their shopping cart.
  • viewCart ("view_cart"): Fired when a user views their shopping cart.

System Events ​

  • apiRequest ("api_request"): Occurs with each API request made by the app.
  • appStartUpComplete ("app_startup_complete"): Indicates the completion of the app's startup process.
  • appCrash ("app_crash"): Fired when the app crashes.
  • featureStartUpComplete ("feature_startup_complete"): Triggered when a feature within the app completes its startup process.

Miscellaneous Events ​

  • other ("other"): Used for any event that does not fit into the predefined categories. This analytics framework allows Hubtel to closely monitor app performance, understand user behaviors, and identify areas for improvement. By analyzing these events, Hubtel can enhance the user experience, streamline processes, and increase overall app effectiveness.

Event Payload ​

json
{
    "action": {
      "actionName": "View"
    },
    "customer": {
      "location": {
        "lat": 5.5739105828285025,
        "lon": -0.3241690993309021
      },
      "customerPhoneNumber": "233546114884",
      "sessionId": "47a748fc-2d27-4eff-80ac-b49bd1c5d12d",
      "station": null,
      "zone": "",
      "country": "5.5739105828285025, -0.3241690993309021",
      "addressName": "5.5739105828285025, -0.3241690993309021"
    },
    "page": {
      "os": "ios",
      "appName": "Hubtel",
      "appType": "App",
      "appCategory": "Customer Apps",
      "analyticsOwner": "Mobile Apps Engineering",
      "appVersion": "6.5.128",
      "appBuildNumber": "1",
      "time": "2024-03-01 12:29:03.318483",
      "isLibrary": null,
      "libraryName": null,
      "libraryVersion": null,
      "libraryOwner": null,
      "pageName": "home",
      "sectionName": "Home",
      "uiType": "Page",
      "viewId": "food__home__view__page_orders",
      "viewName": "Food  Home  View  Page Orders",
      "viewShortName": "Page Orders"
    }
  }

This JSON payload outlines details of a user interaction event within a Hubtel mobile application, specifically focusing on a "View" action. It is structured into three main sections: action, customer, and page, providing a comprehensive snapshot of the event context, user involved, and the app environment at the time of the event.

Action Section ​

  • actionName: Indicates the type of user action, which is "View" in this context, suggesting that the user viewed a particular page or section within the app.

Customer Section ​

  • location: Provides the geographical coordinates (latitude and longitude) of the user, pinpointing their location at the time of the event.
  • customerPhoneNumber: A unique identifier for the user, in this case, a phone number with the country code for Ghana (233).
  • sessionId: Represents a unique session identifier, allowing for the tracking of user activities within a single app session.
  • station: This field is null, indicating that there might be additional context or features within the app not utilized in this event.
  • zone: An empty string, suggesting that no specific zone information is provided or applicable for this event.
  • country and addressName: Both fields repeat the latitude and longitude values, likely meant to provide location context but are formatted as strings instead of providing a country name or address.

Page Section ​

  • os: Specifies the operating system of the device, "iOS", indicating the event was captured from an Apple device.
  • appName: The name of the application, "Hubtel", identifying which app the event is associated with.
  • appType: Clarifies the type of application, here labeled simply as "App".
  • appCategory: Describes the app's category, "Customer Apps", suggesting it's designed for end-users or consumers.
  • analyticsOwner: Indicates the team responsible for the app's analytics, "Mobile Apps Engineering", which could be useful for internal tracking and responsibility allocation.
  • appVersion and appBuildNumber: Provide specific details about the version of the app being used, useful for tracking issues or behaviors across different app releases.
  • time: The exact timestamp when the event occurred, providing insights into user activity timing.
  • libraryName, libraryVersion, libraryOwner, isLibrary: These fields are null, suggesting that the event wasn't triggered by a third-party library or these details aren't applicable for this event.
  • pageName, sectionName, uiType: Offer details about the UI context of the event, indicating the user was viewing the "home" page or section, classified as a "Page" in terms of UI type.
  • viewId, viewName, viewShortName: These identifiers and names give a more detailed description of the viewed page or section, helping to categorize and understand user navigation patterns within the app.

Overall, this payload provides a detailed snapshot of a user interaction event within all Hubtel apps, capturing key data points about the action, the user, and the app environment, which are crucial for analytics and improving user experience.

Consuming Hubtel Mobile Analytics Events via Kafka ​

This document provides a brief guide on how to set up a consumer application to consume Hubtel mobile analytics events using Apache Kafka with the specified configuration settings.

Prerequisites ​

  • Apache Kafka and Zookeeper installed and running.
  • Access to the Kafka cluster configured as per the provided settings.
  • Kafka client library for your preferred programming language (Java, Python, etc.).

Configuration Overview ​

The provided JSON configuration includes key settings for connecting to the Kafka cluster and consuming messages:

  • BootstrapServers: Specifies the Kafka cluster's broker addresses that the consumer will connect to.
  • GroupId: Identifies the consumer group for this application. Kafka uses this ID to manage group offsets and ensure message delivery.
  • Topics: Lists the Kafka topics from which the consumer will read. In this case, it's set to ["hubtel.events.topic"].
  • ExtraProperties: Contains additional consumer configurations. Here, "auto.offset.reset": "earliest" indicates that the consumer should start reading from the earliest message if no previous offset is found.

Step-by-Step Guide ​

  1. Set Up Your Kafka Consumer First, initialize your Kafka consumer in your code. Ensure you include the necessary Kafka client library in your project. Here's an example in Python using the confluent_kafka package:
python
from confluent_kafka import Consumer, KafkaError

# Kafka consumer configuration
config = {
    'bootstrap.servers': 'b-1.eventsstore.8y4zq3.c6.kafka.eu-west-1.amazonaws.com:9092,b-3.eventsstore.8y4zq3.c6.kafka.eu-west-1.amazonaws.com:9092,b-2.eventsstore.8y4zq3.c6.kafka.eu-west-1.amazonaws.com:9092',
    'group.id': 'Hubtel.MobileAnalyticsPg.Consumer',
    'auto.offset.reset': 'earliest'
}

# Initialize the consumer
consumer = Consumer(**config)
  1. Subscribe to the Relevant Topics

Use the consumer to subscribe to the topics listed in your configuration:

python
topics = ['hubtel.events.topic']
consumer.subscribe(topics)
  1. Consume Messages

Implement a loop to continuously listen for and process messages from the topic:

python
try:
    while True:
        msg = consumer.poll(timeout=1.0)  # Adjust the timeout as needed

        if msg is None:
            continue
        if msg.error():
            if msg.error().code() == KafkaError._PARTITION_EOF:
                # End of partition event
                continue
            else:
                print(msg.error())
                break

        # Successfully received a message
        print('Received message: {}'.format(msg.value().decode('utf-8')))

except KeyboardInterrupt:
    pass
finally:
    # Clean up on exit
    consumer.close()
  1. Handling Data

Each message received from Kafka will contain data in the format similar to the event payload example provided earlier. You can deserialize this data (e.g., JSON format) and process it according to your application's logic, such as analytics processing, data storage, or further data transformation tasks.

Notes ​

  • Ensure your consumer application has network access to the specified Kafka brokers.
  • Monitor your consumer's performance and adjust configurations as necessary to optimize for your specific use case and data volume.
  • Implement appropriate error handling and logging to manage and troubleshoot your consumer application effectively.

This guide outlines the basic steps to start consuming Hubtel mobile analytics events from Kafka topics. Depending on your specific requirements, further customization and optimization of the consumer application may be necessary.