|
| 1 | +import { Callout } from 'nextra/components' |
| 2 | + |
| 3 | +# Google Sheets |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +Mixpanel has a native extension for Google Sheets that enables you to import Sheets data to your Mixpanel project, and export your Mixpanel reports/cohorts to your Sheets. |
| 8 | + |
| 9 | +The source code for this extension lives [here](https://github.com/mixpanel/sheets). |
| 10 | + |
| 11 | +<div |
| 12 | + style={{ |
| 13 | + position: "relative", |
| 14 | + paddingBottom: "64.90384615384616%", |
| 15 | + height: 0, |
| 16 | + }} |
| 17 | +> |
| 18 | + <p> |
| 19 | + <iframe |
| 20 | + src="https://www.youtube.com/embed/45ZBaJg-oe4" |
| 21 | + frameBorder="0" |
| 22 | + webkitallowfullscreen="true" |
| 23 | + mozallowfullscreen="true" |
| 24 | + allowFullScreen |
| 25 | + style={{ |
| 26 | + position: "absolute", |
| 27 | + top: 0, |
| 28 | + left: 0, |
| 29 | + width: "100%", |
| 30 | + height: "100%", |
| 31 | + borderRadius: "16px", |
| 32 | + }} |
| 33 | + ></iframe> |
| 34 | + </p> |
| 35 | +</div> |
| 36 | + |
| 37 | +## Install the plugin |
| 38 | + |
| 39 | +Visit the [Sheets ⇔ Mixpanel Google Workspace Marketplace page](https://workspace.google.com/marketplace/app/sheets_%E2%87%94_mixpanel/1078767167468) to install the extension. Learn more about the permissions requested [here](/docs/tracking-methods/integrations/google-sheets#permissions). |
| 40 | + |
| 41 | +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: |
| 42 | + |
| 43 | +<img src="/gsheets-main-menu.png" alt="gsheets-main-menu" /> |
| 44 | + |
| 45 | +- **Sheet → Mixpanel:** import event/user/group/table data from the current sheet. |
| 46 | +- **Mixpanel → Sheet:** export reports or cohort data from your mixpanel project |
| 47 | + |
| 48 | +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. |
| 49 | + |
| 50 | +## Import from Google Sheet |
| 51 | + |
| 52 | +**Sheet → Mixpanel** queries your currently active sheet to get your sheet's column headers. |
| 53 | + |
| 54 | +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: |
| 55 | + |
| 56 | +<img src="/gsheets-mapping.png" alt="gsheets-mapping" /> |
| 57 | + |
| 58 | +Here is a summary of Mixpanel's [data model](/docs/data-structure/concepts) and [required fields for event data](/docs/data-structure/concepts#anatomy-of-an-event): |
| 59 | +- **event name:** what to call each event in mixpanel |
| 60 | +- **distinct_id:** the unique user identifier to whom the event is attributed (learn more [here](/docs/tracking-methods/id-management/identity-management#distinct-id)) |
| 61 | +- **time:** a valid date or time; if the sheet recognizes your chosen column as a 'date' or time', it should work as intended |
| 62 | +- **insert_id:** a value used to deduplicate records (optional) |
| 63 | + |
| 64 | +All other columns in your spreadsheet will get sent as properties (event, user, or group). |
| 65 | + |
| 66 | +You will also need to provide the following details found in your [project settings](/docs/orgs-and-projects/managing-projects#project-details): |
| 67 | +- **project_id** |
| 68 | +- **project_token** |
| 69 | +- **project_region** (data residency) |
| 70 | +- **project_secret** (or [Service Account](https://developer.mixpanel.com/reference/service-accounts)) |
| 71 | + |
| 72 | +<Callout type="warning"> |
| 73 | + Note: since v1.12 syncs are not supported for events. |
| 74 | +</Callout> |
| 75 | + |
| 76 | +Next, learn about [runs and syncs](/docs/tracking-methods/integrations/google-sheets#runs-and-syncs) below. |
| 77 | + |
| 78 | +## Export to Google Sheet |
| 79 | + |
| 80 | +**Mixpanel → Sheet** queries your Mixpanel project for a report or cohort and makes the results available in a new Sheet. |
| 81 | + |
| 82 | +This will replicate the functionality when [exporting a CSV file from the Mixpanel UI](/docs/export-methods#exporting-reports). |
| 83 | + |
| 84 | +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 parse for them automatically: |
| 85 | + |
| 86 | +<img src="/gsheets-parse.gif" alt="gsheets-parse" /> |
| 87 | + |
| 88 | +In case the URL does not contain all the values you need, the UI requires: |
| 89 | +- A [Service Account](https://developer.mixpanel.com/reference/service-accounts) (consumer or higher permission) |
| 90 | +- A report URL with `mixpanel.com` or `eu.mixpanel.com` (to resolve data residency) |
| 91 | +- your [project_id](/docs/orgs-and-projects/managing-projects#viewing-project-information) |
| 92 | +- your [workspace_id](https://developer.mixpanel.com/reference/query-api-authentication#:~:text=Projects%20with%20Data,a%20request%20parameter.) |
| 93 | +- [report_id](https://developer.mixpanel.com/reference/insights-query#:~:text=The%20ID%20of%20your%20Insights%20report%20can%20be%20found%20from%20the%20url%3A%20https%3A//mixpanel.com/report/1/insights%23report/%3CYOUR_BOOKMARK_ID%3E/example%2Dreport) OR [cohort_id](https://developer.mixpanel.com/reference/cohorts-list) |
| 94 | + |
| 95 | +<Callout type="warning"> |
| 96 | + Note: since v1.12 insights, funnels, & retention are the only supported reports. |
| 97 | +</Callout> |
| 98 | + |
| 99 | +Next, learn about [runs and syncs](/docs/tracking-methods/integrations/google-sheets#runs-and-syncs) below. |
| 100 | + |
| 101 | +## Runs and Syncs |
| 102 | + |
| 103 | +Each UI has a similar user interface for you to input your details with four key actions at the bottom: |
| 104 | + |
| 105 | +<img src="/gsheets-four-actions.png" alt="gsheets-four-actions" /> |
| 106 | + |
| 107 | +- **Run:** run the current configuration once; results are display in the UI |
| 108 | +- **Sync:** run the current configuration every hour; run receipts are stored in a log sheet |
| 109 | +- **Save:** store the current configuration |
| 110 | +- **Clear:** delete this sheet's sync and reload the UI |
| 111 | + |
| 112 | +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. |
| 113 | + |
| 114 | +Once created, syncs will run on an hourly schedule; they can also be manually triggered from the main menu by choosing **Sync Now!**: |
| 115 | + |
| 116 | +<img src="/gsheets-sync-now.png" alt="gsheets-sync-now" /> |
| 117 | + |
| 118 | +<Callout type="warning"> |
| 119 | + Note: since v1.12 syncs are not supported for events. |
| 120 | +</Callout> |
| 121 | + |
| 122 | +## Permissions |
| 123 | + |
| 124 | +**Limited User Policy** |
| 125 | + |
| 126 | +Sheets™ ⇔ Mixpanel use and transfer to any other app of information received from Google APIs will adhere to [Google API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy#additional_requirements_for_specific_api_scopes), including the Limited Use requirements. |
| 127 | + |
| 128 | +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. |
| 129 | + |
| 130 | +**Permissions** |
| 131 | + |
| 132 | +Using the principle of least-privilege, Sheets™ ⇔ Mixpanel requests access to three sensitive scopes to support application functionality, which are explained below: |
| 133 | + |
| 134 | +- `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. |
| 135 | +- `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. |
| 136 | +- `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. |
| 137 | + |
| 138 | +No other sensitive scopes are requested by the application. |
0 commit comments