Introduction

Welcome to the Polymatiks Analytics SDK.

This is a library built on top of the Google Analytics. It provides a set of reusable functions to track user interactions and events in your project.

This SDK simplifies the process of sending data to Google Analytics by encapsulating common tracking logic into easy-to-use functions.

Getting Started

Installation

npm install @polymatiks/react-analytics-sdk

//Using CocoaPods
target 'YourAppTarget' do
  pod 'Analytics', :git => 'https://github.com/polymatiks/analytics-ios-sdk.git', :tag => '1.0.0'
end

//Include Polymatiks Maven Repository as a gradle source in your settings.gradle
repositories {
    //...
    maven { url 'https://repository.sdk.polymatiks.ai/repository/maven-public/' }
    //...
}

//Properly include the dependency in your project build.gradle file
dependencies {
    //...
    implementation 'ai.polymatiks:analytics:0.1.0'
    //...
}

The SDK is designed to be easy to integrate into different development environments. Below, you’ll find the steps to install and configure the SDK for the main frameworks: React, Native Android, and Native iOS.

• Javascript
  • Install the SDK using npm

--

• Android (Kotlin)
  • Add Polymatiks maven repository as a source
  • Includes the SKD as a development dependency

--

• iOS (Swift)
  • Includes the SKD from github source as a dependency choosing the latest tag version available

Authentication

// Javascript library automatically takes care of the authentication

import FirebaseApp

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {

        if FirebaseApp.app() == nil {
            let options = FirebaseOptions(
                googleAppID: ProcessInfo.processInfo.environment["POLYMATIKS_APP_ID"] ?? "",
                gcmSenderID: ProcessInfo.processInfo.environment["POLYMATIKS_SENDER_ID"] ?? ""
            )
            options.apiKey = ProcessInfo.processInfo.environment["POLYMATIKS_EVENT_API_KEY"] ?? ""
            options.projectID = ProcessInfo.processInfo.environment["POLYMATIKS_PROJECT_ID"] ?? ""
            options.bundleID = Bundle.main.bundleIdentifier ?? ""

            FirebaseApp.configure(options: options)
        }

        return true
    }
}

// Top-level build file where you can add configuration options common to all sub-projects/modules.
plugins {
    //...
    id 'com.google.gms.google-services' version '4.4.2' apply false
    //...
}

plugins {
    //...
    id 'com.google.gms.google-services'
    //...
}

Authentication in the SDK is simple and integrated, but the process varies slightly depending on the platform. Below, you’ll find the details for setting up authentication in each supported environment.

• Javascript (Automatic): In the JavaScript environment, authentication is handled automatically. Simply initialize the SDK, and it will take care of the entire authentication process in the background. No additional configuration is required.

--

• Android (Credencial File): For native Android projects, you need to add a credentials file in JSON format provided by Google. This file should be placed in the app root directory of your project (same level as the src/ path).

  • Download and place google-services.json in the app module root path
  • Add google-services plugin at the project level build.gradle file
  • Add google-services plugin at the app module level build.gradle file

--

• iOS (appDelegate): For native Swift iOS projects, you need to add a credentials as environment variables and load those settings in an appDelegate file. This file should initialize the settings and be called from the main function.

  • Set the environment variables
    • POLYMATIKS_APP_ID
    • POLYMATIKS_SENDER_ID
    • POLYMATIKS_EVENT_API_KEY
    • POLYMATIKS_PROJECT_ID
  • Create the AppDelegate.swift file to be loaded
  • Add @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate to your @main app struct
  • Additional lib information be found in https://github.com/polymatiks/analytics-ios-sdk

Product Object

const product = {
    id: '123',
    name: 'ACME Anvil',
    price: 17.99,
    fromPrice: 19.99,
    polymatiksPrice: 15.99
}

import Foundation

struct Product: Codable {
    let id: String
    let name: String
    let price: Double
    let fromPrice: Double
    let polymatiksPrice: Double
}

let product = Product(
    id: "123",
    name: "ACME Anvil",
    price: 17.99,
    fromPrice: 19.99,
    polymatiksPrice: 15.99
)

import ai.polymatiks.analytics.Product

val product = Product(
    id = "123",
    name = "ACME Anvil",
    price = 17.99,
    fromPrice = 19.99,
    polymatiksPrice = 15.99
)

Initialize the SDK

import { initPolymatiksAnalytics } from '@polymatiks/react-analytics-sdk';

initPolymatiksAnalytics(customerId, cartId);

import PolymatiksAnalytics

PolymatiksAnalytics.initPolymatiksAnalytics(customerId: "", cartId: "")

import ai.polymatiks.analytics.PolymatiksAnalytics
import ai.polymatiks.analytics.Product

//Initiate your object also giving the Activity context as the first parameter
//Any following events should be triggered using the initiated object
val polymatiksAnalytics = PolymatiksAnalytics(context = this, customerId = '', cartId = '');

Before using the SDK, you need to initialize it.

Keep in mind that this initialization can be triggered everytime when the scenario changes. For example, an user can navigate anonymously (signed out), adding products to a cart and sign in in the middle of the process. So you can start a session without an customerId and update this session once the user sign in.

Parameters

Product View Events

The Product Views Events are a set of analytics events designed to track how users interact with products across different contexts in your application. These events help you understand where and how users are discovering, exploring, and engaging with your products. By capturing these interactions, you can gain valuable insights into user behavior, optimize product placement, and improve the overall user experience.

View Product Page

import { viewProductPageEvent } from '@polymatiks/react-analytics-sdk';

viewProductPageEvent(product);

import PolymatiksAnalytics

PolymatiksAnalytics.viewProductPageEvent(product: Product)

import ai.polymatiks.analytics.Product

polymatiksAnalytics.viewProductPageEvent(Product)

This event is triggered when a user lands on a dedicated product page, where they can view detailed information about the product, such as descriptions, images, pricing, and reviews.

This event is specific to the product page, where the user is likely to spend more time and engage deeply with the product.

• Purpose: Track when a user is actively engaging with a product in a focused manner.
• When to Trigger: When the product page component mounts or when the product data is successfully loaded.
• Example Scenario: A user clicks on a product from a category page and is taken to the product's dedicated page.

Parameters

View Product Home

import { viewProductHomeEvent } from '@polymatiks/react-analytics-sdk';

viewProductHomeEvent(product, position);

import PolymatiksAnalytics

PolymatiksAnalytics.viewProductHomeEvent(product: Product, position: 0)

import ai.polymatiks.analytics.Product

polymatiksAnalytics.viewProductHomeEvent(Product, position = 1)

This event is triggered when a user views a product tile (a small preview of the product) on the home page, typically in a featured or recommended products section.

This event is specific to the home page, where products are often displayed in a condensed format to attract attention.

• Purpose: Track when a user notices a product while browsing the home page.
• When to Trigger: When the product tile becomes visible in the viewport (e.g., using an intersection observer).
• Example Scenario: A user scrolls through the home page and sees a product tile in the "Trending Products" section.

Parameters

View Product Category

import { viewProductCategoryEvent } from '@polymatiks/react-analytics-sdk';

viewProductCategoryEvent(product, categoryId, page, position);

import PolymatiksAnalytics

PolymatiksAnalytics.viewProductCategoryEvent(product: Product, categoryId: "", page: 0, position: 0)

import ai.polymatiks.analytics.Product

polymatiksAnalytics.viewProductCategoryEvent(Product, categoryId = '', page = 1, position = 1)

This event is triggered when a user views a product tile on a category page, where products are grouped by type, brand, or other criteria.

This event is specific to category pages, where users are often comparing multiple products within the same category.

• Purpose: Track when a user is browsing products within a specific category.
• When to Trigger: When the product tile becomes visible in the viewport while the user is on a category page.
• Example Scenario: A user navigates to the "Electronics" category and scrolls through the list of products.

Parameters

View Product Search

import { viewProductSearchEvent } from '@polymatiks/react-analytics-sdk';

viewProductSearchEvent(product, term, page, position);

import PolymatiksAnalytics

PolymatiksAnalytics.viewProductSearchEvent(product: Product, term: "", page: 0, position: 0)

import ai.polymatiks.analytics.Product

polymatiksAnalytics.viewProductSearchEvent(Product, term = '', page = 1, position = 1)

This event is triggered when a user views a product tile on the search results page, typically after performing a search query.

This event is specific to the search page, where users are actively looking for products that match their query.

• Purpose: Track when a user is exploring products based on a specific search term.
• When to Trigger: When the product tile becomes visible in the viewport on the search results page.
• Example Scenario: A user searches for "wireless headphones" and views the product tiles in the search results.

Parameters

View Product Other

import { viewProductEvent } from '@polymatiks/react-analytics-sdk';

viewProductEvent(eventName, product, eventData);

// Not Available

// Not Available

This event is triggered when a user views a product in a context that doesn’t fit the above categories, such as in a popup, modal, recommendation widget, or email.

This event is a catch-all for product views that don’t occur on a standard page or tile.

• Purpose: Track product views in unconventional or secondary contexts.
• When to Trigger: When the product is displayed in a non-standard way (e.g., a "You Might Also Like" widget or a promotional email).
• Example Scenario: A user sees on a product recommendation in a modal that appears after adding an item to their cart.

Parameters

Cart Interaction Events

The Cart Interaction Events are a set of analytics events designed to track how users interact with products in their shopping cart. These events help you understand user behavior during the critical stages of the purchasing journey, such as adding, removing, or modifying products in the cart. By capturing these interactions, you can gain insights into cart abandonment, product preferences, and user intent, enabling you to optimize the checkout process and improve conversion rates.

Cart Add

import { addProductCartEvent } from '@polymatiks/react-analytics-sdk';

addProductCartEvent(product, amount);

import PolymatiksAnalytics

PolymatiksAnalytics.addProductCartEvent(product: Product, amount: 1)

import ai.polymatiks.analytics.Product

polymatiksAnalytics.addProductCartEvent(Product, amount = 1)

This event is triggered when a user adds a product to their shopping cart. It indicates a strong intent to purchase and is a critical step in the conversion funnel.

• Purpose: Measures user interest and intent to purchase specific products.
• When to Use: Track this event when a user clicks the "Add to Cart" button or performs a similar action.
• Example Scenario: A user clicks "Add to Cart" on a product page for a pair of wireless headphones.

Parameters

Cart Remove

import { removeProductCartEvent } from '@polymatiks/react-analytics-sdk';

removeProductCartEvent(product);

import PolymatiksAnalytics

PolymatiksAnalytics.removeProductCartEvent(product: Product)

import ai.polymatiks.analytics.Product

polymatiksAnalytics.removeProductCartEvent(Product)

This event is triggered when a user removes a product from their shopping cart. It helps identify why users abandon certain products before completing their purchase.

• Purpose: Measures reasons for cart abandonment and helps identify potential issues (e.g., pricing, product fit).
• When to Use: Track this event when a user clicks the "Remove" button or performs a similar action in the cart.
• Example Scenario: A user removes a product from their cart because they found a better price elsewhere.

Parameters

Cart Change

import { changeProductCartEvent } from '@polymatiks/react-analytics-sdk';

changeProductCartEvent(product, amount);

import PolymatiksAnalytics

PolymatiksAnalytics.changeProductCartEvent(product: Product, amount: 1)

import ai.polymatiks.analytics.Product

polymatiksAnalytics.changeProductCartEvent(Product, amount = 1)

This event is triggered when a user changes the quantity of a product in their cart, either by increasing or decreasing the amount. It provides insights into user preferences and purchasing behavior.

• Purpose: Measures user intent to purchase in bulk or adjust their order based on needs.
• When to Use: Track this event when a user updates the quantity of a product in the cart (e.g., changing the quantity from 1 to 2).
• Example Scenario: A user increases the quantity of a product in their cart because they want to buy multiple units.

Parameters