Installation

This page takes you from a fresh clone to events arriving in your dashboard. You deploy two things to Cloudflare, the API Worker and the dashboard, and then add the Swift package to your app.

How It Fits Together

Part	Folder	What it does
Swift package	repository root (Package.swift, Sources/Oddlytics)	Queues events in your app and sends them to the Worker in batches.
API Worker	packages/worker	A Cloudflare Worker (built with Hono) that accepts events at /track, stores them in a D1 database, and answers the dashboard's queries.
Dashboard	packages/dashboard	A Next.js app exported as static files. It runs in the browser and calls the Worker directly.

What You Need

• A Cloudflare account. The free tier is enough for personal projects.
• Node.js 18 or later.
• Wrangler, Cloudflare's CLI. The Worker installs it as a dev dependency, so npx wrangler works inside packages/worker. You can also install it globally with npm install -g wrangler.
• Xcode, for the Swift package (Swift tools 5.9).

1. Clone the Repository

git clone https://github.com/OddOmens/Oddlytics.git
cd Oddlytics

2. Deploy the API Worker

Run these from packages/worker. The database schema lives in schema.sql at the repository root, two folders up.

1. Install dependencies and sign in to Cloudflare:

   cd packages/worker
   npm install
   npx wrangler login

2. Create the D1 database:

   npx wrangler d1 create oddlytics-db

   Copy the database_id it prints.

3. Open packages/worker/wrangler.toml and replace the database_id with yours. Keep the binding name DB:

   [[d1_databases]]
   binding = "DB"
   database_name = "oddlytics-db"
   database_id = "YOUR_DATABASE_ID"

4. Create the tables in the deployed database:

   npx wrangler d1 execute oddlytics-db --remote --file=../../schema.sql

5. Set the API key as a Worker secret. Use a long random string, for example from openssl rand -hex 32:

   npx wrangler secret put AUTH_KEY

   Enter the key when prompted. Your apps and the dashboard send this key in the X-API-KEY header.

6. Deploy:

   npx wrangler deploy

   Note the Worker URL it prints, for example https://oddlytics-worker.<your-subdomain>.workers.dev.

7. Check that it responds:

   curl https://oddlytics-worker.<your-subdomain>.workers.dev/

   You should get {"status":"ok","service":"oddlytics-api","version":"1.0.0"}.

TIP

The --remote flag sends the SQL to the database on Cloudflare. Without it, recent versions of Wrangler apply it to a local copy used by wrangler dev.

3. Deploy the Dashboard

The dashboard is a static export (output: 'export' in next.config.js), so it builds to plain files in packages/dashboard/out. Its settings are compiled in at build time.

1. Create packages/dashboard/.env.local:

   NEXT_PUBLIC_API_URL=https://oddlytics-worker.<your-subdomain>.workers.dev
   NEXT_PUBLIC_API_KEY=your-auth-key

   NEXT_PUBLIC_API_KEY must match the Worker's AUTH_KEY. The dashboard needs it to rename events, change app settings and delete data.

2. Build:

   cd packages/dashboard
   npm install
   npm run build

3. Deploy the out folder. Pick one:

   • Cloudflare Pages with Wrangler:

     npx wrangler pages deploy out --project-name=oddlytics-dashboard

   • Cloudflare Pages from GitHub: create a Pages project from your repository with the build command cd packages/dashboard && npm install && npm run build, the output directory packages/dashboard/out, and the two NEXT_PUBLIC_ variables set as environment variables.

   • Vercel: import the repository, set the root directory to packages/dashboard, and add the two environment variables.

WARNING

Anything that starts with NEXT_PUBLIC_ is built into the dashboard's JavaScript, so anyone who can open the dashboard can read the API key. Put the dashboard behind a sign-in, as described next.

4. Protect the Dashboard

Cloudflare Zero Trust can put an email sign-in in front of a Pages site.

The quickest way:

1. In the Cloudflare dashboard, go to Workers & Pages and open your oddlytics-dashboard project.
2. Go to Settings > Access Policy and click Enable Access Policy.
3. Allow only your own email address.

Or, in Cloudflare Zero Trust, go to Access > Applications, click Add an Application, choose Self-hosted, enter your dashboard's domain, and add a policy that allows your email. If you use the .pages.dev address, you may need to add a custom domain to the Pages project first.

After that, visiting the dashboard asks for your email and sends you a one-time code.

5. Add the Swift Package to Your App

1. In Xcode, choose File > Add Package Dependencies...

2. Enter https://github.com/OddOmens/Oddlytics and add the Oddlytics library to your app target.

3. Configure it once at launch and track an event:

   import SwiftUI
   import Oddlytics
   
   @main
   struct MyApp: App {
       init() {
           Analytics.configure(
               endpoint: "https://oddlytics-worker.<your-subdomain>.workers.dev",
               apiKey: "your-auth-key",
               appId: "MyApp"
           )
       }
   
       var body: some Scene {
           WindowGroup {
               ContentView()
                   .onAppear { Analytics.track("app_opened") }
           }
       }
   }

4. Run the app. Events are sent within a few seconds (see Batching and Retries), and the app appears in the dashboard's sidebar and Your Apps list.

The Swift SDK page covers everything else the package does.

Run Everything Locally

For development you can run the Worker and dashboard on your computer with a local D1 database.

1. Give the local Worker an API key. Copy the example file and set a key:

   cd packages/worker
   cp .dev.vars.example .dev.vars

   AUTH_KEY=oddlytics-local-key

2. Create the tables in the local database, then start the Worker:

   npx wrangler d1 execute oddlytics-db --local --file=../../schema.sql
   npm run dev

   Wrangler serves the Worker at http://localhost:8787.

3. In another terminal, start the dashboard:

   cd packages/dashboard
   npm install
   npm run dev

   Without a .env.local, the dashboard uses http://localhost:8787 and the key oddlytics-local-key. Next.js prints the address to open, normally http://localhost:3000.

To put test events in the local database, send them with curl as shown in the API Reference.