# Welcome

Hello! Here's what you need to know to get started.

### **Quick Start**

This is your first step. It's a guide to help you get started fast.

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

### LogSnag for SaaS

Learn how LogSnag can help your SaaS business.

{% content-ref url="/pages/gYv6ORfQAcvFpww3D5ea" %}
[LogSnag for SaaS](/logsnag-for-saas)
{% endcontent-ref %}

### **Our SDKs**

Check these out for an easy way to integrate LogSnag into your product.

[`Node`](/sdks/node) - [`React`](/sdks/react) - [`Next`](/sdks/next) - [`Vue`](/sdks/vue) - [`Deno`](/sdks/deno) - [`Web`](/sdks/web) - [`Python`](/sdks/python)

Also, don't forget to explore our [community-built integrations](/integrations/unofficial).

### **API Reference**

This is your go-to for all the technical details.

[`/log`](/api-reference/log) - [`/identify`](/api-reference/identify) - [`/insight`](/api-reference/insight) 


# Quick Start

Let's Get Started with LogSnag!

## Create a project.

LogSnag lets you make a project for each app you have. You can make as many as you like!

Click the "+" button on the side and give your project a name, like "**my-saas**."

## Create a channel.

Channels are like boxes for your events. You could have one for payments, another for logins, and so on.

Click the "+" button on the side and name your channel "**payments**."

{% hint style="info" %}
Keep your project and channel names simple! Use lowercase for project and channel names, with letters, numbers, and dashes.
{% endhint %}

## Create an API token.

API tokens let LogSnag know it's really you. You can make as many as you like, each with different access levels.

To make an API token, go to the API page in Settings and create and copy a new token.

{% hint style="info" %}
If you're using LogSnag on a website or app that others can see, make sure to set your Token's access to "Public." Also, keep its roles limited to a certain project and channel.
{% endhint %}

## Track your first event.

Now that you have your project, channel, and API token, you're ready to track an event! You can do this by making a POST request to the LogSnag API.

{% tabs %}
{% tab title="cURL" %}

```shell
curl --location --request POST 'https://api.logsnag.com/v1/log' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project": "my-saas",
    "channel": "payments",
    "event": "New Subscription",
    "user_id": "user-123",
    "icon": "💰",
    "notify": true,
    "tags": {
        "plan": "premium",
        "cycle": "monthly",
        "trial": false
    }
}'
```

{% endtab %}

{% tab title="Python" %}

```
pip3 install logsnag
```

```python
from logsnag import LogSnag

logsnag = LogSnag(token='<TOKEN>', project='my-saas')

logsnag.track(
    channel="payments",
    event="New Subscription",
    user_id="user-123",
    icon="💰",
    notify=True,
    tags={
        "plan": "premium",
        "cycle": "monthly",
        "trial": False
    }
)
```

{% endtab %}

{% tab title="JavaScript" %}

```html
<script src="https://cdn.logsnag.com/js/1.0.0/ls.js"></script>
```

```javascript
const logsnag = new window.LogSnag({
  token: '<TOKEN>',
  project: 'my-saas',
})

await logsnag.track({
  channel: "payments",
  event: "New Subscription",
  user_id: "user-123",
  icon: "💰",
  notify: true,
  tags: {
    plan: "premium",
    cycle: "monthly",
    trial: false
  } 
})
```

{% endtab %}

{% tab title="NodeJS" %}

```shell
npm install logsnag
```

```javascript
import { LogSnag } from 'logsnag';

const logsnag = new LogSnag({
  token: '<TOKEN>',
  project: 'my-saas',
})

await logsnag.track({
  channel: "payments",
  event: "New Subscription",
  user_id: "user-123",
  icon: "💰",
  notify: true,
  tags: {
    plan: "premium",
    cycle: "monthly",
    trial: false
  } 
})
```

{% endtab %}

{% tab title="Deno" %}

```typescript
import { LogSnag } from 'https://cdn.logsnag.com/deno/1.0.0/index.ts';

const logsnag = new LogSnag({
  token: '<TOKEN>',
  project: 'my-saas',
})

await logsnag.track({
  channel: "payments",
  event: "New Subscription",
  user_id: "user-123",
  icon: "💰",
  notify: true,
  tags: {
    plan: "premium",
    cycle: "monthly",
    trial: false
  } 
})
```

{% endtab %}
{% endtabs %}

After making the request, you'll get a notification on your device. You'll also see the event pop up in real time on the LogSnag dashboard! It'll be under the **"payments"** channel in the **"my-saas"** project.

Want to learn more about logs? Have a look at the /log endpoint section. You can also check out other endpoints on the API references page.

{% content-ref url="/pages/6994vR8X0vBWH0AoJtg5" %}
[Log](/api-reference/log)
{% endcontent-ref %}

{% content-ref url="/pages/K5zs92Wz1oU9bvKXsjME" %}
[Identify](/api-reference/identify)
{% endcontent-ref %}

{% content-ref url="/pages/VRvto3bU9Y2voy2FS9Oc" %}
[Insight](/api-reference/insight)
{% endcontent-ref %}


# LogSnag for SaaS

LogSnag for SaaS makes it easy to keep track of user events and understand how users behave in your SaaS apps.

## Getting Started

Starting with LogSnag for SaaS is simple. Just add `user_id` to your logs! Then, these logs will link to the user who set off the event. This will help you understand user behavior. You can track events such as `purchase made`, `item added to cart`, `subscription upgraded`, or `support ticket submitted.`

{% hint style="info" %}
We strongly recommend using our in-house SDKs. They simplify the integration process and make it incredibly easy to get started with LogSnag.
{% endhint %}

## User Profiles

After you've sent the first event with a `user_id` parameter, a user profile will be created for that user. This profile will include details about the user, like their first and last seen dates, the number of sessions they've had, their activity usage, their journey within your app, and more.

To learn more about user events, have a look at the /log endpoint section.

{% content-ref url="/pages/6994vR8X0vBWH0AoJtg5" %}
[Log](/api-reference/log)
{% endcontent-ref %}

## User Properties

Besides the fresh charts and metrics generated from user activity, you can also add key-value properties to a user profile.&#x20;

This can be beneficial for incorporating extra information into a user profile, which can then be used for filtering and searching. For instance, you can add details like a user's email address, subscription plan, their last payment date, and more to their profile. This allows you to get a comprehensive view of the user just by looking at their profile.

For more information on user properties, please refer to the /identify endpoint section.

{% content-ref url="/pages/K5zs92Wz1oU9bvKXsjME" %}
[Identify](/api-reference/identify)
{% endcontent-ref %}


# Node

LogSnag client for Node.js applications

### Installation <a href="#user-content-installation" id="user-content-installation"></a>

#### Using npm <a href="#user-content-using-npm" id="user-content-using-npm"></a>

```bash
npm install @logsnag/node
```

#### Using yarn <a href="#user-content-using-yarn" id="user-content-using-yarn"></a>

```bash
yarn add @logsnag/node
```

#### Using pnpm <a href="#user-content-using-pnpm" id="user-content-using-pnpm"></a>

```bash
pnpm add @logsnag/node
```

### Usage <a href="#user-content-usage" id="user-content-usage"></a>

```javascript
import { LogSnag } from '@logsnag/node';

const logsnag = new LogSnag({
  token: '<TOKEN>',
  project: '<PROJECT_NAME>'
});

// Track an event
await logsnag.track({
  channel: "payments",
  event: "New Subscription",
  user_id: "user-123",
  icon: "💰",
  notify: true,
  tags: {
    plan: "premium",
    cycle: "monthly",
    trial: false
  }
});

// Identify user traits (e.g. name, email, plan, etc.)
await logsnag.identify({
  user_id: "user-123",
  properties: {
    name: "John Doe",
    email: "john@doe.com",
    plan: "premium",
  }
});

// Track an insight
await logsnag.insight.track({
  title: "User Count",
  value: "100",
  icon: "👨",
});

// Increment an insight value
await logsnag.insight.increment({
  title: "User Count",
  value: 1,
  icon: "👨",
});
```

### Disabling Tracking <a href="#user-content-disabling-tracking" id="user-content-disabling-tracking"></a>

You can disable tracking for development purposes by using the `disableTracking` method:

```
logsnag.disableTracking();
```

And enable it back with:

```
logsnag.enableTracking();
```

You can check if tracking is disabled with:

```
logsnag.isTrackingDisabled();
```

### Methods <a href="#user-content-methods" id="user-content-methods"></a>

* `track(options: TrackOptions): Promise<boolean>`: Track custom events.
* `identify(options: IdentifyOptions): Promise<boolean>`: Identify user traits.
* `group(options: GroupOptions): Promise<boolean>`: Group users.
* `insightTrack(options: InsightTrackOptions): Promise<boolean>`: Track insights.
* `insightIncrement(options: InsightIncrementOptions): Promise<boolean>`: Increment insight values.


# React

LogSnag client for React applications

### Installation <a href="#installation" id="installation"></a>

#### Using npm <a href="#using-npm" id="using-npm"></a>

```bash
npm install @logsnag/react
```

#### Using yarn <a href="#using-yarn" id="using-yarn"></a>

```bash
yarn add @logsnag/react
```

#### Using pnpm <a href="#using-pnpm" id="using-pnpm"></a>

```bash
pnpm add @logsnag/react
```

### Usage <a href="#usage" id="usage"></a>

First, wrap your application with the `LogSnagProvider` at the top level, passing in your project and token:

> Set your token's scope to `public` in the LogSnag dashboard.

```tsx
import { LogSnagProvider } from '@logsnag/react';

function App() {
  return (
    <LogSnagProvider
      token="<TOKEN>"
      project="<PROJECT_NAME>"
    >
      {/* Rest of your app */}
    </LogSnagProvider>
  );
}
```

### Hooks <a href="#hooks" id="hooks"></a>

The `useLogSnag` hook can be used across your React components and provides the following methods:

* `track(options: TrackOptions)`: Track custom events.
* `identify(options: IdentifyOptions)`: Identify user traits.
* `setUserId(userId: string | null)`: Set the user id for the current user. If the user is not logged in, pass null.
* `clearUserId()`: Clear the user id for the current user.
* `setDebug(flag: boolean = true)`: Set debug mode for logging.

```tsx
import { useLogSnag } from '@logsnag/react';

export function Component() {
  // Get the hooks
  const { setUserId, track, identify } = useLogSnag();

  // Set the user id when a user logs in
  setUserId('user-123');

  // Track an event
  track({
    channel: "payments",
    event: "New Subscription",
    user_id: "user-123", // optional when set using setUserId
    icon: "💰",
    notify: true,
    tags: {
      plan: "premium",
      cycle: "monthly",
      trial: false
    }
  });

  // Identify user traits (e.g., name, email, plan, etc.)
  identify({
    user_id: "user-123", // optional when set using setUserId
    properties: {
      name: "John Doe",
      email: "john@doe.com",
      plan: "premium",
    }
  });

  // Rest of your component
}
```

### Tracking Events <a href="#tracking-events" id="tracking-events"></a>

You can also track events directly from HTML elements using data attributes:

```jsx
<button
    data-event="Upgraded Plan"
    data-user-id="user-123"     // optional (optional when set using setUserId)
    data-channel="billing"      // optional (defaults to "events")
    data-icon=":moneybag:"      // optional
    data-tag-plan="Pro"         // optional
    data-tag-period="Monthly"   // optional
    data-tag-price="9.99"       // optional
>
    Upgrade to Pro
</button>
```

In this example, when the button is clicked, an event named "Upgraded Plan" will be tracked with the specified tags.


# Next

LogSnag client for Next applications

### Installation <a href="#installation" id="installation"></a>

#### Using npm <a href="#using-npm" id="using-npm"></a>

```bash
npm install @logsnag/next
```

#### Using yarn <a href="#using-yarn" id="using-yarn"></a>

```bash
yarn add @logsnag/next
```

#### Using pnpm <a href="#using-pnpm" id="using-pnpm"></a>

```bash
pnpm add @logsnag/next
```

### Usage <a href="#usage" id="usage"></a>

The usage depends on whether you are using the app directory structure or the pages directory structure.

> Set your token's scope to `public` in the LogSnag dashboard

**App Directory:**

In the app directory, you need to import the LogSnagProvider as a head element in your root layout component:

```tsx
import { LogSnagProvider } from '@logsnag/next';

export default function RootLayout({
  children
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <LogSnagProvider token='<TOKEN_NAME>' project='<PROJECT_NAME>' />
        {/* Other head elements */}
      </head>
      <body>
        {/* Your layout */}
        <main>{children}</main>
      </body>
    </html>
  );
}
```

For setting the user id in server components, use the `SetUserIdServerComponent`:

```tsx
import { SetUserIdServerComponent } from '@logsnag/next';

export default function Page() {
  const userId: string | null = 'user-123';
  
  return (
    <>
      {/* Your page content */}
      <SetUserIdServerComponent userId={userId} />
    </>
  );
}
```

**Pages Directory:**

In the pages directory, you can wrap your app with the LogSnagProvider, similar to how you would do in a React application:

```tsx
import { LogSnagProvider } from '@logsnag/next';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <LogSnagProvider token='<TOKEN_NAME>' project='<PROJECT_NAME>'>
      {/* Your app content */}
      <Component {...pageProps} />
    </LogSnagProvider>
  );
}
```

### Hooks <a href="#hooks" id="hooks"></a>

The `useLogSnag` hook can be used across your client components and provides the following methods:

* `track(options: TrackOptions)`: Track custom events.
* `identify(options: IdentifyOptions)`: Identify user traits.
* `setUserId(userId: string | null)`: Set the user id for the current user. If the user is not logged in, pass null.
* `clearUserId()`: Clear the user id for the current user.
* `setDebug(flag: boolean = true)`: Set debug mode for logging.

**Usage:**

```tsx
"use client";
import { useLogSnag } from '@logsnag/next';

export function Component() {
  // Get the hooks
  const { setUserId, track, identify } = useLogSnag();

  // Set the user id when user logs in
  setUserId('user-123');

  // Track an event
  track({
    channel: "payments",
    event: "New Subscription",
    user_id: "user-123", // optional when set using setUserId
    icon: "💰",
    notify: true,
    tags: {
      plan: "premium",
      cycle: "monthly",
      trial: false
    }
  });

  // Identify user traits (e.g., name, email, plan, etc.)
  identify({
    user_id: "user-123", // optional when set using setUserId
    properties: {
      name: "John Doe",
      email: "john@doe.com",
      plan: "premium",
    }
  });

  // Rest of your component
}
```

These hooks have the same usage as their counterparts in the [@logsnag/react](https://www.npmjs.com/package/@logsnag/react) package.

### Tracking Events <a href="#tracking-events" id="tracking-events"></a>

You can also track events directly from HTML elements using data attributes:

```jsx
<button
  data-event="Upgraded Plan"
  data-user-id="user-123"     // optional (optional when set using setUserId)
  data-channel="billing"      // optional (defaults to "events")
  data-icon=":moneybag:"      // optional
  data-tag-plan="Pro"         // optional
  data-tag-period="Monthly"   // optional
  data-tag-price="9.99"       // optional
>
  Upgrade to Pro
</button>
```

In this example, when the button is clicked, an event named "Upgraded Plan" will be tracked with the specified tags.

### Server-side Usage with Next <a href="#server-side-usage-with-next" id="server-side-usage-with-next"></a>

For server-side usage, you can use LogSnag from `@logsnag/next/server` It behaves similarly to [`@logsnag/node`](https://www.npmjs.com/package/@logsnag/node)

> Use a different token for server-side usage and set its scope to `private` in the LogSnag dashboard.

```typescript
import { LogSnag } from '@logsnag/next/server';

// Initialize LogSnagServer
const logsnag = new LogSnag({
  token: '<TOKEN>',
  project: '<PROJECT_NAME>',
});

// Use it in your server-side code
// Track an event
await logsnag.track({
  channel: "payments",
  event: "New Subscription",
  user_id: "user-123",
  icon: "💰",
  notify: true,
  tags: {
    plan: "premium",
    cycle: "monthly",
    trial: false
  }
});

// Identify a user
await logsnag.identify({
  user_id: "user-123",
  properties: {
    name: "John Doe",
    email: "john@doe.com",
    plan: "premium",
  }
});

// Track an insight
await logsnag.insight.track({
  title: "User Count",
  value: "100",
  icon: "👨",
});

// Increment an insight value
await logsnag.insight.increment({
  title: "User Count",
  value: 1,
  icon: "👨",
});
```


# Vue

LogSnag client for Vue applications

### Installation <a href="#installation" id="installation"></a>

#### Using npm <a href="#using-npm" id="using-npm"></a>

```bash
npm install @logsnag/vue
```

#### Using yarn <a href="#using-yarn" id="using-yarn"></a>

```bash
yarn add @logsnag/vue
```

#### Using pnpm <a href="#using-pnpm" id="using-pnpm"></a>

```bash
pnpm add @logsnag/vue
```

### Usage <a href="#usage" id="usage"></a>

First, install the LogSnag plugin in your Vue application:

> Set your token's scope to `public` in the LogSnag dashboard.

```typescript
import { createApp } from 'vue';
import LogSnag from '@logsnag/vue';

const app = createApp(App);

app.use(LogSnag, {
  token: '<TOKEN>',
  project: '<PROJECT_NAME>'
});

app.mount('#app');
```

Then, import the functions you need from the package:

```typescript
import { setUserId, track, identify } from "@logsnag/vue";

// Set the user id for the current user
setUserId('user-123');

// Track an event
track({
  channel: "payments",
  event: "New Subscription",
  user_id: "user-123",
  icon: "💰",
  notify: true,
  tags: {
    plan: "premium",
    cycle: "monthly",
    trial: false
  }
});

// Identify a user
identify({
  user_id: "user-123",
  properties: {
    name: "John Doe",
    email: "john@doe.com",
    plan: "premium",
  }
});
```

You can also track events directly from HTML elements using data attributes:

```html
<button
    data-event="Upgraded Plan" 
    data-channel="billing"
    data-icon=":moneybag:"
    data-tag-plan="Pro"
    data-tag-period="Monthly"
    data-tag-price="9.99"
>
    Upgrade to Pro
</button>
```

In this example, when the button is clicked, an event named "Upgraded Plan" will be tracked with the specified tags.

### Hooks <a href="#hooks" id="hooks"></a>

* `track(options: TrackOptions)`: Track custom events.
* `identify(options: IdentifyOptions)`: Identify user traits.
* `setUserId(userId: string | null)`: Set the user id for the current user. If the user is not logged in, pass null.
* `clearUserId()`: Clear the user id for the current user.
* `setDebug(flag: boolean = true)`: Set debug mode for logging.


# Deno

LogSnag client for Deno applications

### Installation <a href="#installation" id="installation"></a>

```javascript
// Deno's Node.js compatibility mode
import { LogSnag } from 'npm:@logsnag/node';
```

```javascript
// Directly from the CDN.
import { LogSnag } from 'https://dev.jspm.io/@logsnag/node';
```

### Usage <a href="#user-content-usage" id="user-content-usage"></a>

```javascript
const logsnag = new LogSnag({
  token: '<TOKEN>',
  project: '<PROJECT_NAME>'
});

// Track an event
await logsnag.track({
  channel: "payments",
  event: "New Subscription",
  user_id: "user-123",
  icon: "💰",
  notify: true,
  tags: {
    plan: "premium",
    cycle: "monthly",
    trial: false
  }
});

// Identify user traits (e.g. name, email, plan, etc.)
await logsnag.identify({
  user_id: "user-123",
  properties: {
    name: "John Doe",
    email: "john@doe.com",
    plan: "premium",
  }
});

// Track an insight
await logsnag.insight.track({
  title: "User Count",
  value: "100",
  icon: "👨",
});

// Increment an insight value
await logsnag.insight.increment({
  title: "User Count",
  value: 1,
  icon: "👨",
});
```

### Disabling Tracking <a href="#user-content-disabling-tracking" id="user-content-disabling-tracking"></a>

You can disable tracking for development purposes by using the `disableTracking` method:

```
logsnag.disableTracking();
```

And enable it back with:

```
logsnag.enableTracking();
```

You can check if tracking is disabled with:

```
logsnag.isTrackingDisabled();
```

### Methods <a href="#user-content-methods" id="user-content-methods"></a>

* `track(options: TrackOptions): Promise<boolean>`: Track custom events.
* `identify(options: IdentifyOptions): Promise<boolean>`: Identify user traits.
* `group(options: GroupOptions): Promise<boolean>`: Group users.
* `insightTrack(options: InsightTrackOptions): Promise<boolean>`: Track insights.
* `insightIncrement(options: InsightIncrementOptions): Promise<boolean>`: Increment insight values.


# Web

LogSnag Web SDK

### Installation

Add the following script tag to your HTML file to install the web library. Please don't forget to update the `TOKEN` and `PROJECT_NAME` values with your own values.

```html
<script async="true" src="https://cdn.logsnag.com/web/ls.js"></script>
<script>
  window.lsq = window.lsq || [];
  window.ls = window.ls || ((...args) => window.lsq.push(args));
  window.ls("setConfig", "<TOKEN>", "<PROJECT_NAME>");
</script>
```

{% hint style="warning" %}
Please ensure that your token is set to "Public" and its roles are limited to the project you're tracking.
{% endhint %}

### Initialization

This library requires a user id to be set before it starts tracking your events. You can set the user id by calling the `window.ls("setUserId", "<USER_ID>")` function. For example, you could set the user id to the user's email address. Once you've set the user id, LogSnag will start tracking page views and any custom events that you track.

```html
<script>
  window.ls("setUserId", "<SOME_USER_ID>");
</script>
```

### Tracking Events

Tracking custom events is as simple as defining a data attribute on any element. For example, let's track when a user upgrades their plan.

```html
<button
  data-event="Upgraded Plan"
>
  Upgrade to Pro
</button>
```

### Custom Properties

You may add custom properties to your events by defining a data attribute on any element. Remember, the only required property is `data-event`, everything else is optional.

```jsx
<button
  data-event="Upgraded Plan"
  data-user-id="user-123"     // optional (optional when set using window.ls)
  data-channel="billing"      // optional (defaults to "events")
  data-icon=":moneybag:"      // optional
  data-tag-plan="Pro"         // optional
  data-tag-period="Monthly"   // optional
  data-tag-price="9.99"       // optional
>
  Upgrade to Pro
</button>
```


# Python

## Installation

```bash
pip3 install logsnag
```

## Usage

#### Import Library

```python
from logsnag import LogSnag
```

#### Initialize Client

```python
logsnag = LogSnag(token='7f568d735724351757637b1dbf108e5', project="my-saas")
```

#### Track Event

```python
logsnag.track(
    channel="payments",
    event="New Subscription",
    user_id="user-123",
    icon="💰",
    notify=True,
    tags={
        "plan": "premium",
        "cycle": "monthly",
        "trial": False
    }
)
```

#### User Properties

```python
logsnag.identify(
    user_id="user_123",
    properties={
        "name": "John Doe",
        "email": "john@doe.com",
        "plan": "free",
    }
)
```

#### Publish Insight

```python
logsnag.insight.track(
    title='User Count',
    value=100,
    icon='👨',
)
```

#### Increment Insight

```python
logsnag.insight.increment(
    title='User Count',
    value=1,
    icon='👨',
)
```


# Log

Logs are the core of LogSnag. They are used to track events in your application. These events could be anything from user actions to server events, such as a database running out of space or a server crash.

![](/files/YbKi6b5F7VyaGrkmUgWX)

## Publish an event to LogSnag.

<mark style="color:green;">`POST`</mark> `https://api.logsnag.com/v1/log`

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer \<TOKEN>  |

#### Request Body

| Name                                      | Type      | Description              |
| ----------------------------------------- | --------- | ------------------------ |
| project<mark style="color:red;">\*</mark> | String    | Project name             |
| channel<mark style="color:red;">\*</mark> | String    | Channel name             |
| event<mark style="color:red;">\*</mark>   | String    | Event name               |
| description                               | String    | Event description        |
| icon                                      | Emoji     | Single Emoji ✨           |
| notify                                    | Boolean   | Send push notification   |
| tags                                      | key/value | Event tags               |
| parser                                    | String    | "markdown" or "text"     |
| user\_id                                  | String    | User ID                  |
| timestamp                                 | Number    | unix timestamp (seconds) |

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

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Important:** Fields ending with an \* are required in your request!
{% endhint %}

### Icon

You may add an emoji icon to your logs to make identifying the type of event easier. For example, you could add an `💰` icon to a log that tracks a payment event. Optionally, you may use emoji shortcodes instead of the actual emoji character. For example, you could also use `:moneybag:`

### Tags

Tags are key-value pairs that can add additional information to a log. For example, you could add a "plan" tag with a " premium " value to a log that tracks a payment event.

Note that tag keys may only contain lowercase alphabet characters and are optionally separated with `-` dashes. For example, `plan` and `plan-type` are valid tag keys, but `Plan` and `plan_type` are not. Values may be any string, boolean, or number.&#x20;

### Markdown

You may set the parser parameter to `markdown` to parse the description as markdown. This is useful for making your log descriptions more readable and adding links to external resources.

<table><thead><tr><th width="154">Style</th><th width="278">Syntax</th><th>Output</th></tr></thead><tbody><tr><td>Bold</td><td>**bold**</td><td><strong>bold</strong></td></tr><tr><td>Italic</td><td>*italic*</td><td><em>italic</em></td></tr><tr><td>Link</td><td>[link](https://logsnag.com)</td><td><a href="https://logsnag.com">link</a></td></tr><tr><td>Inline Code</td><td>`code`</td><td><code>code</code></td></tr><tr><td>Code Block</td><td>```code```</td><td><code>code</code></td></tr></tbody></table>

### Historical Data

You may add historical logs to LogSnag by adding a `timestamp` parameter to your logs. The timestamp parameter should be a unix timestamp in seconds. Remember that you will not receive a push notification for historical logs.


# Identify

The identify endpoint lets you add key-value properties to a user profile. This endpoint is optional and useful for getting a complete picture of a user just by looking at their profile, and additionally, these properties can be used for filtering and searching.&#x20;

For example, you may add a user's email address, their plan, last payment date, etc., to their profile and then use these properties to filter and search for users, such as searching for all users on a specific plan.

<figure><img src="/files/SWPMCJPItz7BMM0727nr" alt=""><figcaption></figcaption></figure>

## Add properties to user profiles.

<mark style="color:green;">`POST`</mark> `https://api.logsnag.com/v1/identify`

#### Headers

| Name          | Type   | Description      |
| ------------- | ------ | ---------------- |
| Content-Type  | String | application/json |
| Authorization | String | Bearer \<TOKEN>  |

#### Request Body

| Name                                         | Type      | Description     |
| -------------------------------------------- | --------- | --------------- |
| project<mark style="color:red;">\*</mark>    | String    | Project name    |
| user\_id<mark style="color:red;">\*</mark>   | String    | User ID         |
| properties<mark style="color:red;">\*</mark> | Key/Value | User Properties |

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

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Important:** Fields ending with an `*` are required in your request!
{% endhint %}

## Usage

It's important to remember that property keys override each other. For example, imagine that users of our product start with a free trial and then upgrade to a paid plan. We want to track the plan the user is currently on and other properties like their name and email address. We can do this by calling the identify endpoint once the user signs up and again when upgrading to a paid plan.

```json
{
    "project": "my-saas",
    "user_id": "123",
    "properties": {
        "plan": "free",
        "name": "John Doe",
        "email": "john@foo.com",
        "username": "johndoe"
    }
}
```

Later on, when the user upgrades to a paid plan, we can call the identify endpoint again with the new plan value:

```json
{
    "project": "my-saas",
    "user_id": "123",
    "properties": {
        "plan": "premium"
    }
}
```

## Properties Schema

Note that property keys may only contain lowercase alphabet characters and are optionally separated with `-` dashes. For example, `plan` and `plan-type` are valid tag keys, but `Plan` and `plan_type` are not. Values may be any string, boolean, or number.&#x20;


# Insight

Insights are real-time widgets that you can add to each of your projects. They are use-case agnostic and can be used to display any information that you want in real-time.

![](/files/ywlfKBklAbMaIhbJHGnF)

## Publish an insight to LogSnag.

<mark style="color:green;">`POST`</mark> `https://api.logsnag.com/v1/insight`

Insights are real-time events such as KPI, performance, and other metrics that are not captured as a regular event. You can publish them periodically or as soon as they occur and the latest value will be stored in LogSnag.

#### Headers

| Name          | Type   | Description      |
| ------------- | ------ | ---------------- |
| Content-Type  | String | application/json |
| Authorization | String | Bearer \<TOKEN>  |

#### Request Body

| Name                                      | Type           | Description                      |
| ----------------------------------------- | -------------- | -------------------------------- |
| project<mark style="color:red;">\*</mark> | String         | Project name                     |
| title<mark style="color:red;">\*</mark>   | String         | Insight title                    |
| value<mark style="color:red;">\*</mark>   | String, Number | Insight value                    |
| icon                                      | Emoji          | Single emoji as the insight icon |

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

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Important:** Fields ending with an `*` are required in your request!
{% endhint %}

For each insight, the title should remain the same across all updates. However, you may change the value or the icon depending on the status of the insight. For example, if you decide to display the status of a service, you can change the icon to 🟢 if the service is up and 🔴 if it is down.


# Insight Mutate

## Mutate an insight to LogSnag.

<mark style="color:purple;">`PATCH`</mark> `https://api.logsnag.com/v1/insight`

This endpoint allows you to change (mutate) existing numerical insights.

#### Headers

| Name          | Type   | Description      |
| ------------- | ------ | ---------------- |
| Content-Type  | String | application/json |
| Authorization | String | Bearer \<TOKEN>  |

#### Request Body

| Name                                      | Type     | Description                      |
| ----------------------------------------- | -------- | -------------------------------- |
| project<mark style="color:red;">\*</mark> | String   | Project name                     |
| title<mark style="color:red;">\*</mark>   | String   | Insight title                    |
| value<mark style="color:red;">\*</mark>   | Mutation | See example below                |
| icon                                      | Emoji    | Single emoji as the insight icon |

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

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

{% endtab %}
{% endtabs %}

### Mutation Object

#### Increment ($inc)

The increment mutation changes a numerical value by increasing or decreasing it. It can be applied to an existing insight or 0 if no insight exists. The mutation can be performed using either positive or negative numbers.

```json
{
    "project": "makershq",
    "title": "Online Users",
    "value": {
        "$inc": 1
    },
    "icon": "🔴"
}
```

&#x20;


# Feedback Widget

![Frame 525](https://user-images.githubusercontent.com/23535123/181665543-95ee7c9c-c7cc-4a2c-ab5b-7f74e8c54cec.png)

## Usage

Import the widget

```html
<script
  type="module"
  src="https://cdn.logsnag.com/feedback/ls.js"
></script>
```

## Add data tags to your button

```html
<button
  data-logsnag-feedback
  data-logsnag-token="<API_TOKEN>"
  data-logsnag-project="<PROJECT>"
  data-logsnag-channel="<CHANNEL>"
>
  Feedback
</button>
```

## Include User ID

You may include the user id by adding the `data-logsnag-user-id` tag to your button.

```html
<button
  data-logsnag-feedback
  data-logsnag-token="<API_TOKEN>"
  data-logsnag-project="<PROJECT>"
  data-logsnag-channel="<CHANNEL>"
  data-logsnag-user-id="<USER_ID>"
>
  Feedback
</button>
```

## Add custom tags

You may add custom tags to your feedback widget by adding the following data tags to your button.

```html
<button
  data-logsnag-feedback
  <!-- custom username tag -->
  data-logsnag-tag-username="john.doe"
  data-logsnag-token="<API_TOKEN>"
  data-logsnag-project="<PROJECT>"
  data-logsnag-channel="<CHANNEL>"
>
  Feedback
</button>
```

{% hint style="danger" %}
**Important**: Please ensure that your token is set to "Public" and that its roles are limited to the project that you're logging to.
{% endhint %}

<img src="https://user-images.githubusercontent.com/23535123/181601494-93396b89-67da-4538-b535-557b68af12d3.png" alt="Screen Shot 2022-07-28 at 1 34 17 PM" width="912">


# Zapier

{% embed url="<https://zapier.com/developer/public-invite/152393/86138ef81ce1df717a10831ce9b1f07b/>" %}


# Bubble

{% embed url="<https://bubble.io/plugin/logsnag-1645121404900x295452923069202400>" %}


# Unofficial

Following is a list of third-party integrations developed for LogSnag by our amazing community!

{% hint style="info" %}
**Disclaimer**: LogSnag does not provide or maintain these integrations. Due to this, unfortunately, we do not provide support for any question/issue that may arise.
{% endhint %}

## Services and Plugins

#### **Github Action**

{% embed url="<https://github.com/jsmrcaga/action-logsnag>" %}

#### **Directus Integration**

{% embed url="<https://github.com/Intevel/directus-logsnag>" %}

#### Make (Formerly Integromat)

{% embed url="<https://www.make.com/en/hq/app-invitation/3f5e9a0e0db25b9ee1361623308c45b1>" %}

## Languages and Frameworks

#### **C#**

{% embed url="<https://github.com/Seryiia/LogSnagSharp>" %}

#### Dart

{% embed url="<https://github.com/Joran-Dob/logsnag/tree/main>" %}

#### Elixir

{% embed url="<https://github.com/chrisgreg/logsnag_ex>" %}

#### **Go**

{% embed url="<https://github.com/salfatigroup/gologsnag>" %}

#### **Java**

{% embed url="<https://github.com/RiceCX/LogSnag4J>" %}

#### Kotlin

{% embed url="<https://github.com/realdm/Logsnag-Kotlin-Sdk>" %}

#### **Laravel**

{% embed url="<https://github.com/ExpDev07/laravel-logsnag>" %}

#### **PHP**

{% embed url="<https://github.com/hosmelq/laravel-logsnag>" %}

{% embed url="<https://github.com/JoppeDC/LogSnag-PHP-SDK/>" %}

{% embed url="<https://github.com/roublez/logsnag-php>" %}

{% embed url="<https://github.com/davmixcool/logsnag.php>" %}

#### **Ruby**

{% embed url="<https://github.com/deanpcmad/logsnag>" %}

#### **SkriptLang**

{% embed url="<https://github.com/Minematic/SkLogSnag>" %}

#### **Swift**

{% embed url="<https://github.com/Camji55/logsnag-swift>" %}