# Welcome!

Here you'll find our documentation for the APIs, modules and some usage guides.  If you have any questions or feedback, we'd love to talk with you.  Simply contact us via the live-chat or by email at

## First time?

Jump in to the quick start docs and start tracking your app in less than 5 minutes:

{% content-ref url="/pages/NOilzH7K0jy7ixQTC0Z7" %}
[Quick Start](/quick-start)
{% endcontent-ref %}

## Want to deep dive?

Dive a little deeper and start exploring our API reference to get an idea of what's possible with the modules and our APIs:

{% content-ref url="/pages/6rd6DQqUNXpiJz3BSrjQ" %}
[Electron.js / Tauri](/modules/electron.js-tauri)
{% endcontent-ref %}

{% content-ref url="/pages/2vYCr1aPlprSy0stli7Z" %}
[Browser](/modules/browser)
{% endcontent-ref %}

{% content-ref url="/pages/HkbpyPyaBduh2OeM8sau" %}
[Tracking API](/reference/tracking-api)
{% endcontent-ref %}

{% content-ref url="/pages/LlUA6Lsyflox9pIctaX6" %}
[Data API V1](/reference/data-api-v1)
{% endcontent-ref %}


# Quick Start

Getting started with Nucleus is very easy.  By following this short guide you will have the basic functionalities (analytics and bug reports) working in 5 minutes.

## Install the library

The best way to interact with our API is to use one of our official libraries.

By following this short guide you will have the basic functionalities (analytics and bug reports) working in 5 minutes.

### Create an app <a href="#create-an-app" id="create-an-app"></a>

Start by [signing up](https://www.nucleus.sh/signup) on the platform.

Then, create your first app. Name it as you want, you can change it later.

If you already have a version or an icon, you can edit the app to set those.

### Integrate <a href="#integrate" id="integrate"></a>

Choose the appropriate module for your application, or use the API to report data if no module is available for your usecase.

* [Browser](/modules/browser)
* [Electron.js / Tauri](/modules/electron.js-tauri)
* [Python](/modules/python)
* [Swift](/modules/swift)
* [Tracking API](/reference/tracking-api)

Be sure to add the correct `<App Id>` when starting the module.

That's it 🤟

Open your app, and you should be able to see your first user in the Nucleus dashboard.


# Compliance

There are few steps you should take to protect and inform the privacy of your users.

### GDPR & PECR <a href="#gdpr--pecr" id="gdpr--pecr"></a>

Nucleus by default doesn't use or collect IP adresses or any personal information about your users. You can see the total list of data we collect on [this page](https://www.nucleus.sh/transparency).

We do not use cookies even in the Electron version of our software.&#x20;

The only data we store on user devices is a small cache file in case users go offline for the data to be sent later.

That means you are not required by law to ask consent. *However*, we recommend you to read and follow the practices below.&#x20;

{% hint style="info" %}
Whether you need to ask consent to your users before tracking depends on if you plan to report personal identifiable data (with `setProps` or `setUserId`).
{% endhint %}

### Ask Consent... <a href="#ask-consent" id="ask-consent"></a>

This is in the case where you intend to submit personal identifiable information to our servers (by tying personal data and user ID to events you submit).

Ask before starting the analytics session. We recommend doing that before you even load the modules.

Provide the option to your users to disable/enable tracking as they wish.&#x20;

Nucleus' modules support doing that with the `enableTracking()` and `disableTracking()` modules.

### ... or Anonymise <a href="#or-anonymise" id="or-anonymise"></a>

Else, if you still choose to track individual users and report personal data, you should assign them an ID that doesn't allow to identify the original person.&#x20;

That's why email adresses are bad ideas.&#x20;

The same goes when tying properties to your users, those should be at the best extent not personal identifiable informations.

### Inform <a href="#inform" id="inform"></a>

In both cases, you should inform your users what data will be collected about them.

Although you are not required to if you don't submit any personal information, we recommend you mention us in your privacy policy to better inform your users.

If that helps, you can link to our [data transparency](https://www.nucleus.sh/transparency) page that list all the data we collect and store (that doesn't include IP adresses).

Example:

> To get information about the devices and behavior of our users, we use Nucleus to provide analytics. This service gives us insight about how users interact with our software. It does not store any personal identifiable information. Visit their [transparency](https://nucleus.sh/transparency) page to get the full list of data they collect.


# Tracking API

Welcome to the Tracking API.&#x20;

This API should be used when there is no module available for your language or they doesn't satisfy your needs.

We strive to keep it as simple as possible.

Is something missing from the API? Let us know <hello@nucleus.sh>

### Event Types <a href="#events-types" id="events-types"></a>

| Type      | Description                                                                                     | Requires extra data |
| --------- | ----------------------------------------------------------------------------------------------- | ------------------- |
| init      | First event to send when starting the app                                                       | **yes**             |
| event     | Default type, for reporting actions or anything else                                            | no                  |
| error     | Submit an error, `name` should contain the error type                                           | **yes**             |
| userid    | Set a new user ID for this user                                                                 | no                  |
| props     | Set properties for this user ID based on the `data` field.                                      | no                  |
| heartbeat | *Websocket only*: send every minute to keep the connection on. **machineId** field is required. | no                  |

The first thing you need to send when the user opens the app is an **init** event upon which most of the analytics relies on.&#x20;

**If you don't send it first, no data will appear in your dashboard.**

Nucleus uses the **init** event to track the number of sessions. Make sure you send a new **init** event whenever a new session is created. We know it might be difficult to track this properly if you're only sending events from your backend. One solution could be to save the last event timestamp of each session in an in-memory storage and create a new session if more than 30 minutes passed since the last request.

### Events Data <a href="#events-data" id="events-data"></a>

Nucleus expects to receive the analytics data as a JSON object, containing a `data` array property.

This array should contain one or multiple events you want to report.

*Basic events data*

| Parameter | Type    | Optional                                         | Description                                                                                                                                                           |
| --------- | ------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type      | String  | optional                                         | Event type, see below for all the possible values (default: "event")                                                                                                  |
| name      | String  | **required** if `type` is **event** or **error** | Name of the event                                                                                                                                                     |
| sessionId | Integer | **required**                                     | 4-digits number that identifies the current session                                                                                                                   |
| date      | String  | optional                                         | Date/time of the event (ISO 8601 or milliseconds since 1970). If not provided we'll use the time the server receives the event.                                       |
| id        | String  | optional                                         | Short ID that will be returned in confirmation                                                                                                                        |
| userId    | String  | optional                                         | Identify the user with user-facing ID like email, username..                                                                                                          |
| anonId    | String  | optional                                         | Unique user identifier. Ideally should be a [nanoid](https://github.com/ai/nanoid) of 12 chars. More reliable than *userId* and can be used to track anonymous users. |
| deviceId  | String  | **required**                                     | Hashed identifier of the machine (ie mac address)                                                                                                                     |
| payload   | Object  | optional                                         | Additional data attached to the event                                                                                                                                 |

*Extra events data*

If you are reporting either an **error** or the first **init** event, you can attach the following extra data:

| Parameter | Type    | Optional | Example  | Description                                            |
| --------- | ------- | -------- | -------- | ------------------------------------------------------ |
| platform  | String  | required | *Darwin* | Usually 'win32', 'windows', 'mac', 'darwin' or 'linux' |
| osVersion | String  | required | *18.2.0* | Current installed version of the OS                    |
| totalRam  | Integer | required | 8        | Total RAM available on the user device                 |
| version   | String  | required | *0.1.0*  | Version of the app installed                           |
| language  | String  | required | *en-US*  | Locale of the user                                     |

They are not required with regular events to save bandwidth.

Example:

```json
{    
    "data": [{       
     "event": String, // Name of the event        
     "id": String, // OPTIONAL A random id for the event that will be returned when the query succeeds, can be used to make sure no events are reported two times.        
     "userId": String, // A string to identify the user      
     "anonId": String, // 12 chars nanoid identifying the user          
     "deviceId": String, // A hashed identifier of the machine        
     "sessionId": Int, // A random 4-digits number that identifies the current session
     "platform": String, //        
     "osVersion": String, // The version of the OS        
     "totalRam": Int, // The total number of RAM available, in GB        
     "version": String, // Installed version of the app        
     "language": String, // Locale of the user (i.e. 'en-US')        
     "payload": {} // Any additionnal data that you want to report along the event    }]
  }
```

### Track via WebSockets <a href="#track-via-websockets" id="track-via-websockets"></a>

This is the recommended protocol to submit data.&#x20;

It is the most efficient in terms of bandwidth and battery. This is what the modules use behind the scenes.

Latency will be vastly better compared to normal HTTP requests.

**Endpoint:** `wss://app.nucleus.sh/:appId/`

Send your data as a JSON serialized string message.

To prevent data lost due to network errors, when Nucleus receives an event it will send your client a message containing an array `reportedIds` of the previously reported events so you can safely assume they were handled by the server.

### Track via HTTP <a href="#track-via-http" id="track-via-http"></a>

<mark style="color:green;">`POST`</mark> `https://app.nucleus.sh/app/:appId/track`

Use this if you'd like to report data where Websockets aren't available.

Keep in mind that with the HTTP method the "Live view" in the dashboard won't work.

This endpoint doesn't require authentication but is **subject to IP rate limiting**.&#x20;

If you expect lots of events to be reported within a short time interval, you should condense them under one request. For example, save the events in memory (with their correct date), and every 30 seconds report them to the server.

Nucleus will respond with an array `reportedIds` containing the IDs of the events just reported.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app Id |

#### Request Body

| Name                                   | Type  | Description               |
| -------------------------------------- | ----- | ------------------------- |
| data<mark style="color:red;">\*</mark> | Array | Array of `events` objects |


# Data API V1

The Data API v1 is now available. Almost all the data obtained by Nucleus can be retrieved using this API.

{% hint style="info" %}
This API is in beta for now, please let us know if you encounter any issue or if you need to fetch a specific data that isn't documented here, we strive to be fast to respond. We will add more endpoints over time.
{% endhint %}

### Authentication <a href="#authentication" id="authentication"></a>

Nucleus expects the API key to be included in all requests to the server in a auth header:

`Authorization: your_access_token`

Example:

```bash
curl "api_endpoint_here" h -H "Authorization: your_access_token"
```

You may also send it in the body of a POST request as the parameter `token`.

### Quick Glance <a href="#quick-glance" id="quick-glance"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/analytics/quickglance`

Fetch the number of users, installs, sessions and errors during the last 24 hours (and during the previous 24h period for comparison).

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{ 
    "data": {    
        "installs": 35,    
        "users": 15,    
        "appStarts": 205,    
        "errors": 526,    
        "previousInstalls": 26,    
        "previousUsers": 21,    
        "previousAppStarts": 46,    
        "previousErrors": 256  
    }
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics/quickglance" -H "Authorization: your_access_token"
```

### Daily Analytics <a href="#daily-analytics" id="daily-analytics"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/analytics`

The analytics data of your application grouped by day.

You need to supply a date interval as timestamps.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

#### Query Parameters

| Name                                    | Type   | Description                                                                      |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| start<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK " %}

```javascript
// It will return various data on your app like the following. Where each object contains a key/value pair for every day in the period you supplied.
{
  "data": {
    "totalNumbers": {
      "users": 89,
      "installs": 48
    },
    "usage": {
      "2021-04-09": 8,
      "2021-04-10": 25,
      "2021-04-11": 65
    },
    "newUsers": {
      "2021-04-09": 6,
      "2021-04-10": 15,
      "2021-04-11": 25
    },
    "activeUsers": {
      "2021-04-09": 5,
      "2021-04-10": 12,
      "2021-04-11": 21
    },
    "nonNewUsers": {
      "2021-04-09": -1,
      "2021-04-10": 3,
      "2021-04-11": -3
    },
    "hours": {
      "2021-04-09": [
        1,
        1,
        2
      ],
      "2021-04-10": [
        2,
        1,
        1,
        1
      ],
      "2021-04-11": [
        1,
        1,
        1,
        1,
        2,
        2,
        3,
        3
      ]
    },
    "platforms": [
      {
        "value": "linux",
        "count": 12
      },
      {
        "value": "mac",
        "count": 8
      },
      {
        "value": "win",
        "count": 17
      }
    ],
    "ram": [],
    "languages": [
      {
        "value": "en",
        "count": 15
      },
      {
        "value": "fr",
        "count": 8
      }
    ],
    "versions": [
      {
        "value": "0.2.1",
        "count": 55
      }
    ],
    "countries": [
      {
        "value": "BG",
        "count": 6
      },
      {
        "value": "US",
        "count": 20
      }
    ],
    "avgSessionDuration": {
      "2021-04-10": 1789,
      "2021-04-11": 2589.5
    }
  }
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics?start=1618010248&end=1618211950&utcOffset=480"    -H "Authorization: your_access_token"
```

### Events <a href="#events" id="events"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/analytics/events`

The daily stats of your application's events.

You need to supply a date interval as timestamps.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

#### Query Parameters

| Name                                    | Type   | Description                                                                      |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| start<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK It will return details about custom events that you have set in your app tracking." %}

```javascript
{
  "data": {
    "ITEM_PLAYED": {
      "2021-04-11": 256,
      "2021-04-10": 152
    },
    "ITEM_SAVED": {
      "2021-04-11": 314,
      "2021-04-10": 124
    },
    "ITEM_CHECKOUT": {
      "2021-04-11": 289,
      "2021-04-10": 325
    }
  }
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics/events?start=1618010248&end=1618211950&utcOffset=480" -H "Authorization: your_access_token"
```

### Event Properties <a href="#events-properties" id="events-properties"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/analytics/eventsprops`

Get details on the custom data reported alongside your events.

You need to supply a date interval as timestamps.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

#### Query Parameters

| Name                                    | Type   | Description                                                                      |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| start<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK It will return a list of events and attributes (custom data you reported) like the following:" %}

```javascript
{
  "data": [
    {
      "event": "init",
      "keys": [
        "plan",
        "displayName"
      ],
      "type": "string"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics/eventsprops?start=1618010248&end=1618211950&utcOffset=480" -H "Authorization: your_access_token"
```

### Event Attributes <a href="#event-attributes" id="event-attributes"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/analytics/events/:event/:attr`

This will fetch data about a specific event and its attribute.

You need to supply a date interval as timestamps.

#### Path Parameters

| Name                                    | Type   | Description                                                 |
| --------------------------------------- | ------ | ----------------------------------------------------------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID                                                 |
| event<mark style="color:red;">\*</mark> | String | The name of the event to retrieve data                      |
| attr                                    | String | The name of the attribute of the event to retrieve data for |

#### Query Parameters

| Name                                    | Type   | Description                                                                      |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| start<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK It will return data for a specific event and event attribute that is requested" %}

```javascript
{
  "data": [
    {
      "value": "pro",
      "count": 35
    },
    {
      "value": "free",
      "count": 24
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/appId/analytics/events/init/plan?start=1617358132&end=1617962932&utcOffset=480" -H "Authorization: your_access_token"
```

### Errors <a href="#errors" id="errors"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/analytics/errors`

This is your application's error records.

You need to supply a date interval as timestamps.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

#### Query Parameters

| Name                                    | Type   | Description                                                                      |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| start<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK It will return the data for all uncaughtException and unhandledRejection reports as well as any custom error reports that you have set." %}

```javascript
{
  "data": {
    "unhandledRejection": {
      "2021-04-09": 52,
      "2021-04-10": 28,
      "2021-04-11": 75
    },
    "uncaughtException": {
      "2021-04-09": 26,
      "2021-04-10": 37,
      "2021-04-11": 69
    }
  }
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics/errors?start=1618010248&end=1618211950&utcOffset=480"    -H "Authorization: your_access_token"
```

### Users <a href="#users" id="users"></a>

## The Users list for your application.

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/users`

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

{% tabs %}
{% tab title="200: OK It will return all users data" %}

```javascript
{
  "total": 1,
  "data": [
    {
      "_id": "xxxxxxxxxx",
      "userId": "test_user",
      "createdAt": "2021-03-23T06:51:38.633Z",
      "devices": [
        {
          "lastSeen": "2021-03-23T07:42:47.379Z",
          "_id": "xxxxxxxxxx",
          "platform": "win",
          "osVersion": "6.3.9600",
          "version": "0.0.0"
        },
        {
          "lastSeen": "2021-03-23T08:23:44.497Z",
          "_id": "xxxxxxxxxx",
          "platform": "win",
          "osVersion": "8.1",
          "version": "0.0.0"
        }
      ],
      "lastSeen": "2021-03-23T08:23:44.497Z",
      "props": {
        "country": "US",
        "locale": "en"
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/users"    -H "Authorization: your_access_token"
```

### User Details <a href="#user-details" id="user-details"></a>

## User data

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/users/:userId`

#### Path Parameters

| Name                                     | Type   | Description                         |
| ---------------------------------------- | ------ | ----------------------------------- |
| appId<mark style="color:red;">\*</mark>  | String | Your app ID                         |
| userId<mark style="color:red;">\*</mark> | String | ID of the user to fetch details for |

{% tabs %}
{% tab title="200: OK It will return the user details and all its sessions" %}

```javascript
{
  "user": {
    "lastSeen": "2021-03-23T08:23:44.497Z",
    "_id": "xxxxxxxxx",
    "appId": "xxxxxxxxxxxxxxxxxxxxx",
    "userId": "test_user",
    "__v": 0,
    "createdAt": "2021-03-23T06:51:38.633Z",
    "devices": [
      {
        "lastSeen": "2021-03-23T07:42:47.379Z",
        "_id": "xxxxxxxxx",
        "platform": "win",
        "osVersion": "6.3.9600",
        "version": "0.0.0"
      },
      {
        "lastSeen": "2021-03-23T08:23:44.497Z",
        "_id": "xxxxxxxxx",
        "platform": "win",
        "osVersion": "8.1",
        "version": "0.0.0"
      }
    ],
    "props": {
      "country": "US",
      "locale": "en"
    },
    "updatedAt": "2021-03-23T08:23:44.497Z"
  },
  "sessions": [
    {
      "device": "xxxxxxxxx",
      "actions": 1,
      "errors": 0,
      "end": "2021-03-23T07:41:38.479Z",
      "start": "2021-03-23T07:41:38.479Z",
      "session": "xxxxxx"
    },
    {
      "device": "xxxxxxxxx",
      "actions": 1,
      "errors": 0,
      "end": "2021-03-23T06:51:39.980Z",
      "start": "2021-03-23T06:51:39.980Z",
      "session": "xxxxxx"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/users/:userId"    -H "Authorization: your_access_token"
```

### User Session Events <a href="#user-session-events" id="user-session-events"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/users/:userId/session/:sessionId`

This will fetch events data for a specific user session.

You need to supply a device Id in the request parameters, that you can obtain in the previous User Details call.

#### Path Parameters

| Name                                        | Type   | Description                            |
| ------------------------------------------- | ------ | -------------------------------------- |
| appId<mark style="color:red;">\*</mark>     | String | Your app ID                            |
| userId<mark style="color:red;">\*</mark>    | String | ID of the user to fetch details for    |
| sessionId<mark style="color:red;">\*</mark> | Number | ID of the session to retrieve data for |

{% tabs %}
{% tab title="200: OK It will return the list of events of a session made by a specific user" %}

```javascript
{
  "data": [
    {
      "app_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "platform": "win",
      "user_id": "test_user",
      "machine_id": "xxxxxxxxxx",
      "version": "0.0.0",
      "locale": "en",
      "renderer": null,
      "module_version": "2.6.0",
      "avail_ram": 4,
      "type": "init",
      "time": "2021-03-23T09:31:49.647Z",
      "country": "US",
      "arch": "x64",
      "first_time": false,
      "session_id": "xxxx",
      "error_hash": null,
      "os_version": "8.1",
      "data": {
        "plan": "pro"
      },
      "duration": null
    }
  ]
}
```

{% endtab %}
{% endtabs %}

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/users/:userId/session/:sessionId?device=:deviceId"    -H "Authorization: your_access_token"
```

### Delete User <a href="#delete-user" id="delete-user"></a>

<mark style="color:red;">`DELETE`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/users/:userId`

This will delete a specific user (by id) and it's associated data.

#### Path Parameters

| Name                                     | Type   | Description                  |
| ---------------------------------------- | ------ | ---------------------------- |
| appId<mark style="color:red;">\*</mark>  | String | Your app ID                  |
| userID<mark style="color:red;">\*</mark> | String | The ID of the user to delete |

{% tabs %}
{% tab title="204: No Content It will return a 204 code if the user deletion is successful." %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl -X DELETE "https://app.nucleus.sh/api/v1/apps/:appId/users/:userId"    -H "Authorization: your_access_token"
```

### Live Events <a href="#live-events" id="live-events"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/live/events`

This shows real time events data.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/live/events"    -H "Authorization: your_access_token"
```

### Live Users Count <a href="#live-users-count" id="live-users-count"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/live/users/count`

Get the real-time count of how many users are using your app

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

{% tabs %}
{% tab title="200: OK It will return the real-time amount of users" %}

```javascript
{ "data": 234 }
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/live/users/count"    -H "Authorization: your_access_tokenbh
```

### Live Users List <a href="#live-users-list" id="live-users-list"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/live/users`

Get a list of all the users on your app, right now.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

{% tabs %}
{% tab title="200: OK It will return all users data" %}

```javascript
{
  "data": [
    {
      "userDbId": "xxxxxxxxx",
      "userId": "xxxxxxxxx",
      "deviceId": "xxxxxxxxx",
      "platform": "win",
      "osVersion": "8.1",
      "country": "US",
      "lastSeen": "2021-04-12T10:26:08.867Z"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Example:

```bash
curl "https://app.nucleus.sh/api/v1/apps/:appId/live/users"    -H "Authorization: your_access_token"
```


# Electron.js / Tauri

*If you're looking to integrate Astrolytics into a web application instead, check out the* [*Browser SDK*](/modules/browser)*.*

To start using this module, sign up and get an app ID on [Astrolytics.io](https://dash.astrolytics.io).

## Installation

Using npm or yarn (recommended):

```bash
$ npm install astrolytics-desktop
$ yarn add astrolytics-desktop
```

## Usage

First sign-up and get a tracking ID for your app [here](https://nucleus.sh).

With ES6 imports:

```javascript
import Astrolytics from "astrolytics-desktop"
```

Or with CommonJS imports:

```javascript
const Astrolytics = require('astrolytics-desktop')
```

Then:

```javascript
Astrolytics.init("<Your App Id>")

// Optional: sets an user ID
Astrolytics.setUserId("richard_hendrix")

// Report things
Astrolytics.track("PLAYED_TRACK", {
  trackName: "My Awesome Song",
  duration: 120,
})
```

You only need to call `init` once.

### Options

You can init Astrolytics with options:

```javascript
import Astrolytics from "astrolytics-desktop"

Astrolytics.init("<Your App Id>", {
  deviceId: null, // device id (optional)
  disableInDev: false, // disable module while in development (default: false)
  disableTracking: false, // completely disable tracking from the start (default: false)
  disableErrorReports: false, // disable errors reporting (default: false)
  sessionTimeout: 60 * 60, // in seconds, after how much inactivity a session expires
  useOldDeviceId: false, // use the legacy device ID (default: false)
  debug: true, // Show logs
})

```

**Each property is optional**. You can start using the module with just the app ID.

The module will try to autodetect a maximum of data as possible but some can fail to detect. It will tell you in the logs which one it failed to detect.

You can manually add data:

```javascript
Astrolytics.setProps({
  version: "0.3.1",
  locale: "fr",
  // ...
})
```

### Electron Version detection

Version detection only works on Electron's main process as newest Electron versions don't supply the remote module version.

To get the version programmatically in Electron's renderer process you need to [setup the remote object](https://github.com/electron/remote), you can then track the version with:

```javascript
const { app } = require('@electron/remote')

Astrolytics.setProps({
  version: app.getVersion(),
})
```

### Identify your users

You can track specific users actions on the 'User Explorer' section of your dashboard.

For that, you need to supply an `userId`, a string that will allow you to track your users.

It can be your own generated ID, an email, username... etc.

```javascript
Astrolytics.identify("someUniqueUserId")
```

You can also pass custom attributes to be reported along with it.

```javascript
Astrolytics.identify("someUniqueUserId", {
  age: 34,
  name: "Richard Hendricks",
  jobType: "CEO",
})
```

If you call `.identify()` multiple times, the last one will be remembered as the current user data (it will overwrite).

Later on, you can update the userId only (and keep the attributes) with this method:

```javascript
Astrolytics.setUserId("someUniqueUserId")
```

### Update user attributes

You can report custom user attributes along with the automatic data.

Those will be visible in your user dashboard if you previously set an user ID.

The module will remember past properties so you can use `Astrolytics.setProps` multiple times without overwriting past props.

Properties can either **numbers**, **strings** or **booleans**. Nested properties or arrays aren't supported at the moment.

```javascript
Astrolytics.setProps({
  age: 34,
  name: "Richard Hendricks",
  jobType: "CEO",
})
```

Overwrite past properties by setting the second parameter as true.

```javascript
Astrolytics.setProps({
  age: 23
}, true)
```

### Events

Send your own events and track user actions:

```javascript
Astrolytics.track("PLAYED_TRACK")
```

They are a couple event names that are reserved by Astrolytics: `init`, `error:` and `astrolytics:`. Don't report events containing these strings.

#### Attach custom data

You can also add extra information to tracked events, as a JSON object.

Properties can either **numbers**, **strings** or **booleans**. Nested properties or arrays aren't supported at the moment (they won't show in the dashboard).

Example

```javascript
Astrolytics.track("PLAYED_TRACK", {
  trackName: "My Awesome Song",
  duration: 120,
})
```

#### Pages and Screen Views

You can set up Astrolytics to track page visits and screen views in your app.

For that, whenever the user navigates to a different page, call the `.page()` method with the new view name.

```javascript
Astrolytics.page("View Name")
```

You can attach extra info about the view. Example:

```javascript
Astrolytics.page("Cart", {
  action: "addItem",
  count: 5
})
```

Params can either be **numbers**, **strings** or **booleans**. Nested params or arrays aren't supported at the moment (they won't show in the dashboard).

### Toggle tracking

This will completely disable any communication with Astrolytics' servers.

To opt-out your users from tracking, use the following methods:

```javascript
Astrolytics.disableTracking()
```

and to opt back in:

```javascript
Astrolytics.enableTracking()
```

This change won't persist after restarts so you have to handle the saving of the settings.

You can also supply a `disableTracking: true` option to the module on start if you want to directly prevent tracking.

### Error tracking

Astrolytics will by default report all `uncaughtException`, `unhandledRejection` and `windowError` events.

If you'd like to report another type of error, you can do so with:

```javascript
Astrolytics.trackError("myCustomError", err)
```

Contact **<hello@astrolytics.io>** for any inquiry


# Browser

![Astrolytics](https://intriguing-lemonade-efa.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2Fb00319ab-5801-40dc-b0f4-5de683b11d61%2Fgithub_browser_sdk_banner.jpg?id=9fabfb89-61d3-4d87-97ff-ef88c9bd8947\&table=block)

## Table of Contents

1. [Getting Started](broken://pages/I7m4BWAZn1JthYSZsJU1)
2. [Usage](broken://pages/I7m4BWAZn1JthYSZsJU1)
3. [How to Contribute](broken://pages/I7m4BWAZn1JthYSZsJU1)

## Getting Started

To get started with Astrolytics, create an account at [Astrolytics](https://dash.astrolytics.io/signup) and grab the App ID, then use the SDK to start tracking events.

### Installation

As NPM package (recommended)

```bash
# with npm
npm install astrolytics-browser

# or with yarn
yarn add astrolytics-browser
```

or as browser script

```
<script src="https://cdn.jsdelivr.net/npm/astrolytics-browser/dist/bundle.iife.js"></script>
```

we recommend using a specific version in case a non-backwards compatible change is introduced

```
<script src="https://cdn.jsdelivr.net/npm/astrolytics-browser@<version>/dist/bundle.iife.js"></script>
```

### Usage

```javascript
import Astrolytics from 'astrolytics-browser';

Astrolytics.init('YOUR_APP_ID');
```

Replace `'YOUR_APP_ID'` with the unique ID of your app. You can get it [here](https://dash.nucleus.sh/account).

You can check examples with different frameworks here.

## API

Astrolytics supports passing the following options as second argument to the `Astrolytics.init()` method:

```js
Astrolytics.init('APP_ID', {
  endpoint: 'wss://app.astrolytics.io', // only option, we don't allow self hosting yet :(
  disableInDev: true, // disable in development mode. We recommend not to call
                      // `init` method, as that will be more reliable.
  debug: false, // if set to `true`, will log a bunch of things.
  disableTracking: false, // will not track anything. You can also use `Astrolytics.disableTracking()`.
                          // note that some events will still be added to the queue, so if you call
                          // Astrolytics.enableTracking() again, they will be sent to the server.
  automaticPageTracking: true, // will track all page changes.
  reportInterval: 2 * 1000, // at which interval the events are sent to the server.
  sessionTimeout: 60 * 30 * 1000, // time after which the session is ended
  cutoff: 60 * 60 * 48 * 1000, // time after which event that were not sent yet are deleted
  disableErrorReports: false, // wether to disable error tracking
})
```

### Tracking

Track events with optional custom data

```javascript
Astrolytics.track("click", { foo: 'bar' });
```

### Error Tracking

Track errors with a name and the Error object.

```javascript
Astrolytics.trackError(name, error);
```

By default Astrolytics will listen for `window.onerror` and `window.onunhandledrejection` events and send them to the API. If you want to disable this behaviour, you can set `disableErrorReports` to `true`:

```js
Astrolytics.init('APP_ID', { disableErrorReports: true })
```

### User Identification

Identify a user by a unique ID and optionally set custom properties.

```javascript
Astrolytics.identify('04f8846d-ecca-4a81-8740-f6428ceb7f7b', { firstName: 'Brendan', lastName: 'Eich' });
```

### Page Tracking

Track page views with the page name and optional parameters. If the page name is not provided, the current window's pathname is used.

```javascript
Astrolytics.page('/about', { foo: 'baz' });
```

By default, Astrolytics will track any page change by polling the url every 50 ms. If you prefer to manually track page changes, set `automaticPageTracking` to false and call `Astrolytics.page()` on every page change.

### Disabling Tracking

To disable tracking

```javascript
Astrolytics.disableTracking();
```

### Enabling Tracking

To enable tracking

```javascript
Astrolytics.enableTracking();
```


# Python

We tried to make it as simple as possible to report the data you need to analyze your app usage and improve it.

This module is compatible with Python 3+.

To start using this module, sign up and get an app ID on [Nucleus.sh](https://nucleus.sh/).

### Installation

```bash
$ pip install nucleus-python
```

### Basic usage

Add the following code to import Nucleus and init the analytics.

Don't use the `import ... from` syntax as you won't be able to set the module options like `app_id`.

```
import nucleus

nucleus.app_id = 'your app id'

nucleus.set_props({
	'version': '0.5.0', # Set app version (Nucleus cannot detect it)
	'userId': 'richard_hendrix'
})

nucleus.app_started()
```

**Only use `app_started()` once per session, if you are using Nucleus in several files call app\_started() the earliest possible.**

Sign up and get a tracking ID for your app [here](https://nucleus.sh/).

#### Options

You can init Nucleus with options:

```
nucleus.report_interval = 20 # interval (in seconds) between server com
nucleus.disable_tracking = False # completely disable tracking
nucleus.debug = False # Show internal logs to help debug
nucleus.auto_user_id = False # Assign the user an ID
```

#### Identify users

You can track specific users actions on the 'User Explorer' section of your dashboard by assigning an user ID.

It can be any value as long as it is a *string*.

```
nucleus.set_user_id('someUniqueUserId')
```

Alternatively, set the `auto_user_id` option of the module to `True` to automatically assign the user an ID based on his username and hostname.

#### Modify automatic data

You can overwrite some properties or fill data that wasn't detected.

*You have to do it before calling `app_started()` for this to work*

It is a good idea to set your app version directly as Nucleus **cannot detect it** for the moment.

```
nucleus.set_props({
	'version': '0.5.0',
	'locale': 'en_US'
})
```

#### Track custom data

You can also add custom data along with the automatic data.

Those will be visible in your user dashboard *if you previously set an user ID*.

The module will remember past properties so you can use `nucleus.set_props` multiple times without overwriting past props.

Properties can either **numbers**, **strings** or **booleans**. Nested properties or arrays aren't supported at the moment.

```
nucleus.set_props({
	"age": 34,
	"name": 'Richard Hendricks',
	"job": 'CEO'
})
```

To overwrite past properties, set the second parameter to `True`.

```
nucleus.set_props({
	"age": 23
}, True)
```

#### Errors

To catch errors with Nucleus, simply add the tracking code to an exception and pass the exception as the unique parameter.

Nucleus will extract the relevant informations and show them in your dashboard.

```
try:
    my_app()
except Exception as e:
	nucleus.track_error(e)
```

Add this at the outermost level of your code to handle any otherwise uncaught exceptions before terminating.

The advantage of except Exception over the bare except is that there are a few exceptions that it wont catch, most obviously KeyboardInterrupt and SystemExit.

#### Events

After initializing Nucleus, you can send your own custom events.

```
nucleus.track("PLAYED_TRACK")
```

They are a couple event names that are reserved by Nucleus: `init`, `error:` and `nucleus:`.

You shouldn't report events containing these strings.

**Tracking with data**

You can add extra information to tracked events, as an object.

Properties can either **numbers**, **strings** or **booleans**.

Nested properties or arrays aren't supported at the moment.

Example:

```
nucleus.track("PLAYED_TRACK", data = {
	"trackName": 'My Awesome Song',
	"duration": 120
})
```

#### Toggle tracking

This will completely disable any communication with Nucleus' servers.

To opt-out your users from tracking:

```
nucleus.disable_tracking()
```

and to opt back in:

```
nucleus.enable_tracking()
```

This doesn't persist after restarts so you have to handle saving the setting.


# Swift

*This module is in beta. Send us an email in case of any integration issue.*

Analytics, licensing and bug reports for Swift MacOS applications.

We made it as simple as possible to report the data you need to analyze your app and improve it.

To start using this package, sign up and get an app tracking ID on [Nucleus.sh](https://nucleus.sh/).

*Make sure to check enable both "Incoming and outgoing connections" for your app in XCode under "Signing & Capabilities"*

If you have a server-side Swift application, or maybe a cross-platform (for example Linux & macOS) app/library, and you would like to log, we think targeting this logging API package is a great idea. Below you'll find all you need to know to get started.

### Usage

Sign up and get a tracking ID for your app [here](https://nucleus.sh/).

```
.package(url: "https://github.com/nucleus-sh/NucleusSwift.git", from: "1.0.0"),
```

and to your application/library target, add "NucleusSwift" to your dependencies, e.g. like this:

```
.target(name: "ExampleApp", dependencies: ["NucleusSwift"]),
```

In AppDelegate, import the library

```
import NucleusSwift
Nucleus.shared.setup("my-app-id")

...
func applicationDidFinishLaunching(_ aNotification: Notification) {
    ...
    Nucleus.shared.appStarted()
}
```

Then you can use the module from anywhere in your app:

```
Nucleus.shared.track("BTN-CLICKED")

Nucleus.shared.setUserId("richard_hendrix")
```

**Debugging**

If you are having troubles with the module it can be useful to enable logging:

```
Nucleus.shared.debug = true
```

#### Identify your users

You can track specific users actions on the 'User Explorer' section of your dashboard.

For that, you can supply an `userId` when initing the Nucleus module.

It can be your own generated ID, an email, username... etc.

```
Nucleus.shared.setUserId("someUniqueUserId")
```

#### Add properties

You can report custom data along with the automatic data.

Those will be visible in your user dashboard if you previously set an user ID.

The module will remember past properties so you can use `Nucleus.shared.setProps` multiple times without overwriting past props.

Properties can either **numbers**, **strings** or **booleans**. Nested properties or arrays aren't supported at the moment.

```
Nucleus.shared.setProps([
    "age": 34,
    "name": "Richard Hendricks",
    "jobType": "CEO"
])
```

Enable overwrite: set the second parameter as true to overwrite past properties.

```
Nucleus.shared.setProps([
    "age": 23
], overwrite: true)
```

#### Events

After initializing Nucleus, you can report your own custom events.

```
Nucleus.shared.track("PLAYED_TRACK")
```

They are a couple event names that are reserved by Nucleus: `init`, `error:` and `nucleus:`. Don't report events containing these strings.

**Attach more data**

You can also add extra information to tracked events. Properties can either **numbers**, **strings** or **booleans**. Nested properties or arrays aren't supported at the moment.

Example

```
Nucleus.track("PLAYED_TRACK", [
    "trackName": "My Awesome Song",
    "duration": 120
])
```

#### Errors

You can catch and report errors. That can be useful to debug what went wrong once your app is deployed in production.

You need to supply an ID and a message to your errors. The package will extract a stracktrace that you will be able to see in your dashboard.

Example

```
Nucleus.shared.trackError(id: "API-ERROR", message: "Missing required parameter")
```

#### Toggle tracking

This will completely disable any communication with Nucleus' servers.

To opt-out your users from tracking, use the following methods:

```
Nucleus.shared.disableTracking()
```

and to opt back in:

```
Nucleus.shared.enableTracking()
```

This change won't persist after restarts so you have to handle the saving of the settings.


# React Native

![Nucleus.sh](https://intriguing-lemonade-efa.notion.site/image/https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fsecure.notion-static.com%2F98020d0c-fd01-43ff-a29e-8f1c8f30de4b%2Fmsdncsmcnsm.jpg?table=block\&id=db0f27a3-321c-400e-9ca7-db0213d1dee1)

## Table of Contents

1. [Getting Started](broken://pages/S4W2dfa3oqxsQZxHLlSI)
2. [Usage](broken://pages/S4W2dfa3oqxsQZxHLlSI)
3. [How to Contribute](broken://pages/S4W2dfa3oqxsQZxHLlSI)

## Getting Started

To get started with Nucleus, create an account at [Nucleus](https://dash.nucleus.sh/login) and grab the App ID, then use the SDK to start tracking events.

### Installation

This package has `@react-native-async-storage/async-storage` and `@react-native-community/netinfo` as peer dependencies. Install them first if you don't have them

```bash
yarn add @react-native-async-storage/async-storage @react-native-community/netinfo
```

then proceed to install `nucleus-rn` As NPM package (recommended)

```bash
# with yarn
yarn add nucleus-rn
```

### Usage

```javascript
import Nucleus from 'nucleus-rn';

Nucleus.init('YOUR_APP_ID');
```

Replace `'YOUR_APP_ID'` with the unique ID of your app. You can get it [here](https://dash.nucleus.sh/account).

You can check examples with different frameworks here.

## API

Nucleus supports passing the following options as second argument to the `Nucleus.init()` method:

```js
Nucleus.init('APP_ID', {
  appVersion: '0.0.0', // the version of your application
  endpoint: 'wss://app.nucleus.sh', // only option, we don't allow self hosting yet :(
  disableInDev: true, // disable in development mode. We recommend not to call
                      // `init` method, as that will be more reliable.
  debug: false, // if set to `true`, will log a bunch of things.
  disableTracking: false, // will not track anything. You can also use `Nucleus.disableTracking()`.
                          // note that some events will still be added to the queue, so if you call
                          // Nucleus.enableTracking() again, they will be sent to the server.
  reportInterval: 2 * 1000, // at which interval the events are sent to the server.
  sessionTimeout: 60 * 30 * 1000, // time after which the session is ended
  cutoff: 60 * 60 * 48 * 1000, // time after which event that were not sent yet are deleted
  disableErrorReports: false, // wether to disable error tracking
})
```

### Tracking

Track events with optional custom data

```javascript
Nucleus.track("click", { foo: 'bar' });
```

### Error Tracking

Track errors with a name and the Error object.

```javascript
Nucleus.trackError(name, error);
```

By default Nucleus registers a handler for `ErrorUtils.setGlobalHandler` that sends `'GlobalError'` errors to the API. If you want to disable this behaviour, you can set `disableErrorReports` to `true`:

```js
Nucleus.init('APP_ID', { disableErrorReports: true })
```

and catch errors manually using `Nucleus.trackError('an error', errObject)`.

### User Identification

Identify a user by a unique ID and optionally set custom properties.

```javascript
Nucleus.identify('04f8846d-ecca-4a81-8740-f6428ceb7f7b', { firstName: 'Jordan', lastName: 'Walke' });
```

### Screen tracking

Track screen views with the screen name and optional parameters.

```javascript
Nucleus.page('/about', { foo: 'baz' });
```

### Disabling Tracking

To disable tracking

```javascript
Nucleus.disableTracking();
```

### Enabling Tracking

To enable tracking

```javascript
Nucleus.enableTracking();
```

## How to Contribute

We're always looking for contributions from the community. Here's how you can help:

1. **Report Bugs**: Create an issue report detailing the bug you've found.
2. **Suggest Features**: Have a great idea for Nucleus? Don't hesitate to put it forward by creating an issue.
3. **Submit Pull Requests**: Feel free to fix a bug or add a new feature and create a pull request. Make sure to follow the existing code style, and write clear commit messages explaining your changes.