🧮 sheets ⇔ mixpanel

connect your google sheet with mixpanel! no coding required!

👔 tldr;

after installing you will see the sheets ⇔ mixpanel dropdown under extensions in any google sheet. this module provides two modes, which are exposed in the main menu:

Sheet → Mixpanel: import event/user/group/table data from the current sheet.
Mixpanel → Sheet: export reports or cohort data from your mixpanel project

each UI has a simple user interface, and is essentially a form you fill out that contains the necessary details to carry out your desired result.

🍿 demo

🗺️ mappings (sheet → mixpanel)

sheet → mixpanel queries your currently active sheet to get your sheet's column headers.

once you choose the type of data you are importing, you will use the visual mapper to connect the column headers from your sheet to the required fields for the type of mixpanel data you are importing:

as a brief summary of the documentation mixpanel's data model for events requires fields for:

event name : what to call each event in mixpanel
distinct_id : the unique user identifier to whom the event is attributed
time : a valid date or time; if the sheet recognizes your chosen column as a 'date' or time', it should work as intended
insert_id : a value used to deduplicate records (optional)

all other columns in your spreadsheet will get sent as properties (event, user, or group)

you'll also need to provide :

project id
project token
project region
either:
- service account (admin or higher) OR
- API secret

note: since v1.12 syncs are not supported for events.

next, read about runs + syncs

💽 exports (mixpanel → sheet)

mixpanel → sheet queries your mixpanel project for a report or cohort and makes the results available in a new sheet.

note that this will be identical to the functionality would get when exporting a CSV file from the mixpanel UI:

there are a number of parameters needed to fetch a CSV from mixpanel; the simplest way to gather those parameters is to paste the URL of the report/cohort you wish to sync from your mixpanel project, and the app should find them:

in case the URL does not contain all the values you need, the UI requires:

a service account (consumer or higher)
a URL with either mixpanel.com or eu.mixpanel.com (to resolve data residency)
your project id
your workspace id
and either:
- your report id OR
- your cohort id

you can manually type these values in after pasting in a URL.

note: as of v1.12 insights, funnels, & retention are the only supported reports

next, read about runs + syncs

🔄 runs + syncs

each UI has a similar user interface for you to input your details with four key actions at the bottom:

Run: run the current configuration once; results are display in the UI
- Sync: run the current configuration every hour; run receipts are stored in a log sheet
- Save: store the current configuration
- Clear: delete this sheet's sync and reload the UI

you may only have one sync active per sheet at a time.

if you are planning to sync data from your sheet to mixpanel, it is recommended that you do a "run" first.

once created, syncs will run on an hourly schedule; they can also be manually triggered from the main menu by choosing Sync Now!:

note: since v1.12 syncs are not supported for events.

👨‍🔧️ development

local development

For local development, you will need to do the following:

clone the repo: git clone https://github.com/ak--47/sheets-mixpanel.git
install dev dependencies: npm install
install clasp globally: npm i g clasp
create a google sheet by importing the provided test data
in the google sheets UI, go to Extensions → AppsScript → Project Settings to get your scriptId:

using the scriptId create a .clasp.json file of the form:

{
"scriptId": "your-googleApps-script-id",
"rootDir": "/path/to/this",
"projectId": "your-gcp-project"
}

run clasp login to create a .clasprc.json file of the form:

{
"token": {
    "access_token": "",
    "scope": "",
    "token_type": "",
    "id_token": "",
    "expiry_date": ,
    "refresh_token": ""
},
"oauth2ClientSettings": {
    "clientId": "",
    "clientSecret": "",
    "redirectUri": "http://localhost"
},
"isLocalCreds": true
}

see these docs for more info

finally:

use npm run push to push the module's code into your instance
see package.json for other scripts; anything with a watch prefix will re-run on local code changes

code overview

Here's an overview of the code in the repo:

├── Code.js             # routes + templates
├── README.md           # this file
├── appsscript.json     # extension manifest
├── components          # data in/out logic
│   ├── dataExport.js
│   └── dataImport.js
├── creds.json          # server-side credentials
├── env-sample.js       # where test credentials go
├── env.js
├── jsconfig.json       # typescript config
├── models              # models for data import
│   ├── modelEvents.js
│   ├── modelGroups.js
│   ├── modelTables.js
│   └── modelUsers.js
├── package-lock.json
├── package.json        # scripts + dependencies
├── testData            # test data
│   ├── events.csv
│   ├── full\ sandbox.xlsx  # (use this one)
│   ├── groups.csv
│   ├── tables.csv
│   └── users.csv
├── tests               # local + server tests
│   ├── MockData.js
│   ├── UnitTestingApp.js
│   └── all.test.js
├── types               # jsdoc + typescript types
│   ├── Types.d.ts
│   └── Types.js
├── ui                  # user interface
│   ├── mixpanel-to-sheet.html
│   └── sheet-to-mixpanel.html
└── utilities           
    ├── REPL.js         # a "quick and dirty" REPL for GAS
    ├── flush.js        # sending data to mixpanel
    ├── md5.js          # for $insert_id construction
    ├── misc.js         # various utilities
    ├── sheet.js        # for manipulating sheets
    ├── storage.js      # modifying storage configuration
    ├── toJson.js       # turn CSV to JSON
    ├── tracker.js      # usage tracking
    └── validate.js     # validation utils

tests

you can run local tests with the watch-test-local script:

npm run watch-test-local

you can run server-side tests with the test-server script:

npm run test-server

in order for server-side tests to work, you will need to fill out params in a env.js file... there is a sample (env-sample.js) committed to the repo; this is what passing server-side tests look like (in the GCP console):

📝 limited use policy

Sheets™ ⇔ Mixpanel use and transfer to any other app of information received from Google APIs will adhere to Google API Services User Data Policy, including the Limited Use requirements.

The app is free to use and does not contain ads, nor will any data collected by Sheets™ ⇔ Mixpanel be resold in any way. No human can read your spreadsheets; usage data is collected and anonymized only to improve the end-user's experience.

🔏 permissions

Using the principle of least-privilege, Sheets™ ⇔ Mixpanel requests access to three sensitive scopes to support application functionality, which are explained below:

https://www.googleapis.com/auth/script.container.ui is used to draw a dynamic UI which maps the columns headers of your currently active Google Sheet™ into dropdowns in the extension interface.
https://www.googleapis.com/auth/script.scriptapp is used to support scheduled hourly "sync" functionality so the pipeline you've configured in the UI can run automatically.
https://www.googleapis.com/auth/script.external_request is used to send your mapped data to mixpanel and to request your report/cohort data from mixpanel.

no other sensitive scopes are requested by the application.

💬 motivation

google sheets are databases. mixpanel is a database. it should be easy to make these things interoperable. now it is!

that's it for now. have fun!

mixpanel / sheets

readme