From 971e423e42130a0e3740676775fb5709b8de1bba Mon Sep 17 00:00:00 2001 From: goenning Date: Fri, 1 Sep 2023 19:35:26 +0100 Subject: [PATCH] added docs for react --- packages/react/CHANGELOG.md | 3 + packages/react/README.md | 113 ++++++++++++++++++++++++++++++++++++ packages/web/CHANGELOG.md | 4 ++ packages/web/README.md | 2 + packages/web/package.json | 2 +- 5 files changed, 123 insertions(+), 1 deletion(-) diff --git a/packages/react/CHANGELOG.md b/packages/react/CHANGELOG.md index e69de29..a240c3d 100644 --- a/packages/react/CHANGELOG.md +++ b/packages/react/CHANGELOG.md @@ -0,0 +1,3 @@ +## 0.1.0 + +- Initial version of the React SDK for Aptabase diff --git a/packages/react/README.md b/packages/react/README.md index e69de29..2258589 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -0,0 +1,113 @@ +![Aptabase](https://aptabase.com/og.png) + +# React SDK for Aptabase + +A tiny SDK (1 kB) to instrument your React apps with Aptabase, an Open Source, Privacy-First and Simple Analytics for Mobile, Desktop and Web Apps. + +## Setup + +1. Install the SDK using your preferred JavaScript package manager + +```bash +npm add @aptabase/react +``` + +2. Get your `App Key` from Aptabase, you can find it in the `Instructions` menu on the left side menu. + +3. Initialize the `AptabaseProvider` component to your app based on your framework. + +
+ Setup for Next.js (App Router) + + Add `AptabaseProvider` to your RootLayout component: + +```tsx +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + {children} + + + ); +} +``` + +
+ +
+ Setup for Next.js (Pages Router) +
+ +
+ Setup for Remix +
+ +
+ Setup for Create React App or Vite + +Add `AptabaseProvider` to your root component: + +```tsx +import { AptabaseProvider } from '@aptabase/react'; + +ReactDOM.createRoot(root).render( + + + + + , +); +``` + +
+ +## Advanced setup + +The `AptabaseProvider` also supports an optional second parameter, which is an object with the `appVersion` property. + +It's up to you to decide what to get the version of your app, but it's generally recommended to use your bundler (like Webpack, Vite, Rollup, etc.) to inject the values at build time. + +## Tracking Events with Aptabase + +After setting up the `AptabaseProvider`, you can then start tracking events using the `useAptabase` hook. + +Here's an example of a simple counter component that tracks the `increment` and `decrement` events: + +```js +'use client'; + +import { useState } from 'react'; +import { useAptabase } from '@aptabase/react'; + +export function Counter() { + const { trackEvent } = useAptabase(); + const [count, setCount] = useState(0); + + function increment() { + setCount((c) => c + 1); + trackEvent('increment', { count }); + } + + function decrement() { + setCount((c) => c - 1); + trackEvent('decrement', { count }); + } + + return ( +
+

Count: {count}

+ + +
+ ); +} +``` + +A few important notes: + +1. The SDK will automatically enhance the event with some useful information, like the OS, the app version, and other things. +2. You're in control of what gets sent to Aptabase. This SDK does not automatically track any events, you need to call `trackEvent` manually. + - Because of this, it's generally recommended to at least track an event at startup +3. You do not need to await the `trackEvent` function, it'll run in the background. +4. Only strings and numbers values are allowed on custom properties diff --git a/packages/web/CHANGELOG.md b/packages/web/CHANGELOG.md index 7c4acff..73d50a5 100644 --- a/packages/web/CHANGELOG.md +++ b/packages/web/CHANGELOG.md @@ -1,3 +1,7 @@ +## 0.2.0 + +- Some internal refactor to support the new `@aptabase/react` package + ## 0.1.3 - Add automatic session timeout after 1 hour of inactivity diff --git a/packages/web/README.md b/packages/web/README.md index fb12269..a5e81ab 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -4,6 +4,8 @@ A tiny SDK (1 kB) to instrument your web app with Aptabase, an Open Source, Privacy-First and Simple Analytics for Mobile, Desktop and Web Apps. +Building a React app? Use the `@aptabase/react` package instead. + > 👉 **IMPORTANT** > > This SDK is for **Web Applications**, not websites. There's a subtle, but important difference. A web app is often a lot more interactive and does not cause a full page reload when the user interacts with it. It's often called a **Single-Page Application**. A website, on the other hand, is a lot more content-focused like marketing sites, landing pages, blogs, etc. While you can certainly use Aptabase to track events on websites, please be aware that each page reload will be considered a new session. diff --git a/packages/web/package.json b/packages/web/package.json index 9589e4e..a47e22d 100644 --- a/packages/web/package.json +++ b/packages/web/package.json @@ -1,6 +1,6 @@ { "name": "@aptabase/web", - "version": "0.1.3", + "version": "0.2.0", "type": "module", "description": "JavaScript SDK for Aptabase: Open Source, Privacy-First and Simple Analytics for Mobile, Desktop and Web Apps", "main": "./dist/index.cjs",