Latest 0.1.0
Homepage https://github.com/Movile/analytics-generator
License MIT
Platforms osx , ios , tvos , watchos
Authors

Analytics Generator

A tool to unify analytics event definitions between projects with same analytics pre-requisites. Using it you can ensure two projetcs, say iOS and Android, will share the same analytics event specs, avoiding discrepancy in event names, missing event parameters and so on.

The main idea is to keep in a remote repository a file with event specs (in json format). This tool will download it and generate the code that will be used in the projects.

The advantages are:

  • The names of events and parameters will be generated, so the developer will not to worry about typing (or mistyping) it. This will avoid bugs of discrepancy in strings between different platforms.
  • A method for each event will be generated, with one argument for each specified event parameter. By calling this method, the compiler will ensure no parameters will be forgotten.
  • Always the analytics specs changes, that will reflect in all projects. If names change, almost no coding will be necessary. If parameters be add, the compiler will warning about it. All changes should be easy and safe.

Preparing

Before integrate the tool with your project, you need to generate it. Open the project AnalyticsGenerator with Xcode and run it. Under the group Products you will find a command line tool named analytics-generator. You will need move it to your project.

Getting Started with Xcode

Install via Cocoapods

Add a new pod and run pod install

pod 'AnalyticsGenerator'

Install manually

  1. Open the Xcode project
  2. Build it
  3. Open the directory Products in the Project navigator
  4. Find the binary analytics-generator
  5. Copy it to any directory inside your project. Let’s say, tools/analytics-generator.

Create a config file

Inside your project, create anywhere a config file named, for example, Config, with the following content

source = http://remote-path-to-share-files/name-of-analytics-specs.json
target = AnalyticsEvents.swift
version = 0.0.1

Create a Build Phase

In Xcode, create a build phase (preferably before the phase Compile Sources) with the following command

$PODS_ROOT/AnalyticsGenerator/analytics-generator -config $SRCROOT/path-to-config/Config

Or, if the tool was added manually,

./path/analytics-generator -config $SRCROOT/path-to-config/Config

Build

Build the project. A file named AnalyticsEvents.swift will be generated at same location of config file. This swift file must be added to the project.

Getting Started with Android Studio

Install

Copy the command line tool analytics-generator to any directory inside your project. Let’s say, tools/analytics-generator.

Create a config file

Inside your project, create anywhere a config file named, for example, Config, with the following content

source = http://remote-path-to-share-files/name-of-analytics-specs.json
target = AnalyticsEvents.kt
version = 0.0.1

Setup Gradle

In the topmost build.gradle file of your project, add a new task

task generate_analytics {
    exec {
        executable './tools/analytics-generator'
        args '-config', './path-to-config/Config'
    }
}

Build

Sync Gradle. A file named AnalyticsEvents.kt will be generated at same location of config file. This kotlin file will be used by your project.

Coding

Sending events

The generated swift/kotlin file will contain methods with all event parameters you want to send to your analytics clients. Instead sending events by the traditional way

let eventName = "My event"

let params: [String: Any] = [
    "Name": "Content name",
    "ID": 123,
    "Premium": true
]

sendEventWith(name: eventName, params: params)

You can now use an auto-generated method

let attrs = AnalyticsEvents.myEvent(name: "Content name", id: 123, premium: true)

sendEventWith(name: attrs.name, params: attrs.parameters)

In kotlin it looks like this

val attrs = AnalyticsEvents.myEvent("Content name", 123, true)

sendEventAttributes(attrs.name, attrs.parameters)

Setuping the JSON

The event name and it parameters will be defined in the shared json, following the structure

{
    "events": [{
        "name": "My Event",
        "params": [{
            "name": "Name",
            "type": "string"
        }, {
            "name": "ID",
            "type": "integer"
        }, {
            "name": "Premium",
            "type": "boolean"
        }]
    }]
}

Generated files

The following files will be generated:

  • JSON The remote json with analytics specs will be downloaded to config directory. This file is only a local version of the shared json, so you should not edit it since it will be replaced every time the shared json changes. This file need not to be added to your project or repository since it can be downloaded again, but also you can do it.

  • Config.lock This file keeps the last downloaded version. Whenever Config.lock and Config versions differs, the json is downloaded again and the swift file is re-generated. Is important to add this file to your repository. When is desired to update the json, the Config version can be updated or Config.lock file can be deleted.

  • Swift file This file (as example AnalyticsEvents.swift) must be added to your project. Since it will be generated again every time the json version changes, is usefull to do not change this file location so it will be automatically updated.

  • Kotlin file This file (as example AnalyticsEvents.kt) must be in your project. Are valid the same rules as for swift.

JSON Structure

Common types

These common types will be translated to equivalent types in swift and kotlin: string, integer, float, double, boolean.

Dates

The type timestamp can be used to dates. It will be translated to TimeInterval in swift and Long in kotlin.

Optional parameters

Each parameter can be marked with optional, so it won’t need be sent. If omitted, the parameter will be considered as required.

{
    "events": [{
        "name": "My Event",
        "params": [{
            "name": "Name",
            "type": "string",
            "optional": true
        }]
    }]
}

Enums

Instead a common type, an event parameter can be in a set of possible values. For example,

{
    "events": [{
        "name": "My Event",
        "params": [{
            "name": "Screen",
            "type": ["Home", "Settings", "Profile"]
        }]
    }]
}

will generate an enum in swift and an enum class in kotlin, containing the types for home, settings and profile. Only strings values are supported.

Built With

  • Swift

Latest podspec

{
    "name": "AnalyticsGenerator",
    "version": "0.1.0",
    "summary": "A tool to unify analytics event definitions between projects with same analytics pre-requisites",
    "description": "A tool to unify analytics event definitions between projects with same analytics pre-requisites. Using it you can ensure two projetcs, say iOS and Android, will share the same analytics event specs, avoiding discrepancy in event names, missing event parameters and so on.",
    "homepage": "https://github.com/Movile/analytics-generator",
    "license": "MIT",
    "authors": {
        "[email protected]": "[email protected]"
    },
    "source": {
        "http": "https://github.com/Movile/analytics-generator/releases/download/0.1.0/analytics-generator.zip"
    },
    "preserve_paths": "*",
    "platforms": {
        "osx": null,
        "ios": null,
        "tvos": null,
        "watchos": null
    }
}

Pin It on Pinterest

Share This