Plausible-to-Fivetran Cloud Function

A Google Cloud Function that fetches analytics data from Plausible and streams it into Fivetran. This function syncs data at multiple time granularities (hourly, daily, weekly, monthly) to provide accurate unique visitor counts for any reporting period.

---

Table of Contents

• Plausible-to-Fivetran Cloud Function
  • Table of Contents
  • Overview
  • Output Tables
  • Setup and Deployment
  • Configuration
  • Usage
  • Why Multiple Granularities?
  • Testing the Integration
  • Troubleshooting
  • About IMG.LY
  • License

---

Overview

This repository contains a Node.js function meant to be deployed on Google Cloud Functions. It leverages Fivetran's function connector to sync Plausible analytics data on a regular schedule. The function:

• Reads secrets (plausibleApiKey, siteId, and optionally timezone) from the Fivetran request body.
• Queries Plausible's v2 analytics API at multiple time granularities.
• Returns data in a format Fivetran can ingest (including state, table schemas, and pagination indicators).
• Automatically handles incremental syncs and rate limiting.

---

Output Tables

The connector creates four tables in your destination, each with the same schema but different time granularity:

Table	Granularity	Best Used For
timeseries_hourly	Per hour	Traffic patterns, peak hours analysis
timeseries_daily	Per day	Daily trends, accurate daily unique visitors
timeseries_weekly	Per week	Weekly trends, week-over-week comparisons
timeseries_monthly	Per month	Monthly reporting, accurate monthly unique visitors

Schema

All tables share the same columns:

Column	Type	Description
timestamp	TIMESTAMP	UTC timestamp (primary key)
visitors	INTEGER	Unique visitors in the period
visits	INTEGER	Total sessions/visits
pageviews	INTEGER	Total page views
bounce_rate	FLOAT	Bounce rate percentage
visit_duration	FLOAT	Average visit duration in seconds

---

Setup and Deployment

Use the instructions in the official Fivetran Google Cloud Functions setup guide to deploy this function. Make sure to:

1. Provide this repository's code as your function source.
2. Set the entry point to syncWithPlausible.
3. Configure the following secrets in Fivetran's Configuration:

Secret	Required	Description
plausibleApiKey	Yes	Your Plausible API key (create one here)
siteId	Yes	Your Plausible site domain (e.g., example.com)
timezone	No	Site's reporting timezone (default: Europe/Berlin)

---

Configuration

Timezone

The timezone secret should match your Plausible dashboard's configured timezone. This ensures timestamps are correctly converted to UTC. Common values:

• Europe/Berlin
• America/New_York
• America/Los_Angeles
• UTC

See the full list of timezone identifiers.

Internal Settings

These can be adjusted in the code if needed:

• PAGE_SIZE: Number of records fetched per API call (default: 1000)
• METRICS: List of metrics synced (visitors, visits, pageviews, bounce_rate, visit_duration)

---

Usage

Initial Sync

1. Fivetran calls the function with no state.
2. The function fetches all historical data for each granularity, cycling through hourly → daily → weekly → monthly.
3. Each granularity is paginated independently (1000 rows per call).
4. State is updated after each granularity completes.

Incremental Sync

1. On subsequent calls, Fivetran includes the saved state.
2. The function queries only new data since the last sync for each granularity.
3. The cycle continues: hourly → daily → weekly → monthly → done.

Sync Cycle Example

Call 1: hourly page 1 (1000 rows) → hasMore=true
Call 2: hourly page 2 (1000 rows) → hasMore=true
Call 3: hourly page 3 (500 rows)  → hourly done, advance to daily
Call 4: daily (all rows)          → daily done, advance to weekly
Call 5: weekly (all rows)         → weekly done, advance to monthly
Call 6: monthly (all rows)        → cycle complete, hasMore=false

---

Why Multiple Granularities?

The Problem: Plausible's "visitors" metric is deduplicated within each time bucket. A visitor who visits at 10am and 3pm counts as:

• 1 visitor in the 10am hour
• 1 visitor in the 3pm hour
• But only 1 unique visitor for the day

If you sum hourly visitor counts, you'll get an inflated number (overcounting by ~15-25%).

The Solution: This connector syncs data at multiple granularities:

• Use timeseries_hourly for traffic pattern analysis
• Use timeseries_daily for accurate daily unique visitor counts
• Use timeseries_monthly for accurate monthly reporting that matches Plausible's UI

---

Testing the Integration

Connection Test

Fivetran's Test Connection calls the function with setup_test = true. The function performs a minimal API request to verify credentials and endpoint availability.

Local Testing

Run the function locally with the Functions Framework:

npm install
npx functions-framework --target=syncWithPlausible --port=8080

Then POST a request to http://localhost:8080/:

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": {
      "plausibleApiKey": "YOUR_API_KEY",
      "siteId": "YOUR_SITE_ID",
      "timezone": "Europe/Berlin"
    },
    "state": {},
    "setup_test": false
  }'

---

Troubleshooting

Rate Limiting (429 Error)

Plausible has a rate limit of 600 requests per hour. If you hit this limit:

• The connector will return a RateLimitError
• Fivetran will automatically retry after a delay
• Consider increasing the sync interval if this happens frequently

Authentication Error (401)

• Verify your plausibleApiKey is correct
• Ensure the API key has access to the specified site

Invalid Site (404)

• Check that siteId exactly matches your site domain in Plausible
• The site ID is case-sensitive

Timezone Mismatch

If your data timestamps seem offset:

• Verify the timezone secret matches your Plausible dashboard settings
• Default is Europe/Berlin if not specified

---

About IMG.LY

Need a powerful image editing SDK for your next project? Check out IMG.LY. Our CreativeEditor SDK provides easy-to-integrate photo and video editing capabilities for web, iOS, and Android. Join thousands of developers who use IMG.LY to enhance their apps with filtering, transformations, stickers, and more—helping users unleash their creativity right inside your product.

---

License

This project is open source, released under the MIT License. You are free to use, modify, and distribute this code as permitted under the license terms.

---

Happy Syncing!