Add documentation for the Google Analytics import

docs/delete-site-data.md

@@ -4,6 +4,6 @@ title: Delete your site data and your stats
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-Within the "**Danger zone**" section of your website settings you can delete your site from Plausible Analytics. This also removes all the stats you've collected until that point. Click on the big red "**Delete**" button to delete your site and your stats from Plausible Analytics.
+Within the "**Danger zone**" section of your website settings you can delete your site from Plausible Analytics. This also removes all the stats you've collected until that point, including any imported data. Click on the big red "**Delete**" button to delete your site and your stats from Plausible Analytics.
 
 <img alt="Delete your site data and your stats" src={useBaseUrl('img/delete-site-data.png')} />

docs/filters-segments.md

@@ -18,6 +18,10 @@ Your current filters will be displayed on the top of your dashboard. You can cli
 
 You can remove all of your filters by hitting the `Esc` key on your keyboard or by selecting `Clear all filters` in the filters menu that shows up when you're using multiple filters.
 
+:::note
+Imported data cannot be filtered and is excluded from the dashboard when a filter is enabled. See for [here](google-analytics-import.md#what-is-imported) more details.
+:::
+
 ## Using the "Add filter" menu for extra functionality 
 
 <img alt="Using the custom filter" src={useBaseUrl('img/custom-filter.png')} />

docs/google-analytics-import.md

@@ -0,0 +1,76 @@
+---
+title: Importing data from Google Analytics
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+If you have already collected data for your website using Google Analytics (GA)
+and want to import that data into Plausible, you can do this as follows:
+
+1. Go to the general settings page for your site.
+2. In the **Data Import** panel, link your Google account to your Plausible account.
+3. You will now see a dropdown selection menu listing GA profiles that were
+   found associated with your Google account. Select the appropriate profile;
+   this will generally be the profile with the same domain name as this
+   Plausible site. The selection also displays the profile's permissions which
+   should say "All Web Site Data". If you do not have a profile for your domain
+   name with those permissions, for example if your Google Account only has
+   access to a view of another account's data, you may need to obtain greater
+   permissions for your Google account.
+
+<img alt="Select GA profile" src={useBaseUrl('img/import-select-profile.png')} />
+
+4. Clicking **Import** will schedule the data import. Depending on the amount
+   of data you have, this may take some time. This is run in the background, so
+   you will receive an email when the import has completed.
+5. Once you have received the email, the imported data will be visible in your
+   Plausible dashboard.
+
+## What is imported?
+
+Data is imported in aggregate for each date, and only from dates up to your
+first Plausible-collected data to avoid double-counting visits.
+
+The GA data is imported using Google's Reporting API v4, which has limits on
+the number of dimensions that can be fetched in a single query. This means we
+cannot fetch entries that contain all of the dimensions we are interested in,
+and instead need to fetch data for each dimension individually. Unfortunately,
+this means we are unable to look at how dimensions interact. For example, we
+cannot apply a filter to the dashboard while still including imported data.
+
+An indicator is displayed near the top of the dashboard when imported data has
+been included:
+
+<img alt="Imported data indicator" src={useBaseUrl('img/imported-data-included.png')} />
+
+Clicking this indicator will toggle the inclusion of imported data. If data has
+been excluded manually rather than because it is incompatible with the current
+view (i.e. while a filter is in use), the indicator will appear with a
+strikethrough:
+
+<img alt="Imported data being excluded" src={useBaseUrl('img/imported-data-excluded.png')} />
+
+### Sources
+
+GA aggregates multiple dimensions under the name **source**, including referral
+sources and the value of the UTM source parameter if that was present during a
+visit. If AdWords autotagging was enabled for a visit then this takes the value
+"google". This means that for any visits that used a UTM source parameter we
+are unable to get the referrer. The compromise we have made with this problem
+is to save referrers - identified as being domain names - as **sources** and
+everything else as **UTM sources**. In the case of AdWord tracking, this is
+saved as a **UTM source** with the value "adwords".
+
+### Locations
+
+While the Reporting API lets us fetch data about which countries visitors
+connect from, it does not give us access to region and city location data in a
+standard format. For each visit recorded by GA, we will have its country but
+that visit will have an unknown region and city.
+
+## Deleting imported data
+
+Data that you have imported can be deleted by returning to your site's general
+settings page and clicking the "Forget imported stats" button:
+
+<img alt="Forget imported data" src={useBaseUrl('img/imported-data-forget.png')} />

docs/reset-site-data.md

@@ -4,6 +4,6 @@ title: Reset your site data
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-Within the "**Danger zone**" section of [your website settings](website-settings.md) you can reset your website stats. This removes all the stats you've collected until that point. Click on the "**Reset**" button to reset your stats from Plausible Analytics.
+Within the "**Danger zone**" section of [your website settings](website-settings.md) you can reset your website stats. This removes all the stats you've collected until that point, including any imported data. Click on the "**Reset**" button to reset your stats from Plausible Analytics.
 
 <img alt="Reset your site data" src={useBaseUrl('img/delete-site-data.png')} />

docs/self-hosting-configuration.md

@@ -88,9 +88,9 @@ To make this as easy as possible you can use the [`maxmindinc/geoipupdate`](http
 You just need to add your account details, mount the database in the `plausible` container and let the image update the database automatically.
 To run the complete setup including geoip see [`docker-compose-geoip.yml`](https://github.com/plausible/hosting/blob/master/geoip/docker-compose.geoip.yml).
 
-### Google Search Integration
+### Google Integration
 
-To enable the Google Search Console integration, as is described elsewhere in the [docs](google-search-console-integration.md), you first need to authorize your self-hosted installation with a Google Account. Complete the following three tasks to do so.
+Plausible supports integration with [Google Search Console](google-search-console-integration.md) and importing data from [Google Analytics](google-analytics-import.md). Both of these features require your self-hosted installation be authorized with a Google account. Complete the following three tasks to do so.
 
 #### Task One: Create an OAuth Client
 
@@ -123,35 +123,37 @@ To enable the Google Search Console integration, as is described elsewhere in th
 
 1. Follow the prompts or select "OAuth consent screen" from the left side menu to configure the consent screen. If you can't see the "OAuth consent screen" menu item, open the navigation ("hamburger") menu in the top left corner and select "APIs & Services". "OAuth consent screen" is a menu item below that.
 
-1. Enter an "App name" and a "User support email". Again, to help with naming, remember that the "app" is your self-hosted Plausible site which will be requesting access to the Search Console API using your Google Account, so you are probably the only user.
+1. Enter an "App name" and a "User support email". Again, to help with naming, remember that the "app" is your self-hosted Plausible site which will be requesting access to the Search Console API and/or Analytics Reporting API using your Google Account, so you are probably the only user.
 
 1. Apart from the mandatory "Developer contact information" fields, the only other necessary setting is the "Authorized domains" which must include the domain used for the earlier "Authorized Redirect URIs" setting. That is, add the domain (eg. `example.com`) of your Plausible installation's public URL. All subdomains will be authorized automatically.
 
 1. Click "SAVE AND CONTINUE". No "Scopes" are required, so click "SAVE AND CONTINUE" again.
 
 1. The "app" will be created with status set to "Testing". To avoid having to verify it with Google, you must enter the email address of your Google Account as a "Test user". Add the email address and then click "SAVE AND CONTINUE" and the OAuth Consent Screen configuration is complete.
 
-#### Task Three: Enable Google Search Console API
+#### Task Three: Enable Google APIs
 
-Although you can now grant your Plausible installation access to your Google account, you still will not be able to choose a property from the Search Console as described in [Google Search Console Integration](google-search-console-integration.md), until you enable the "[Google Search Console API](https://console.developers.google.com/apis/api/searchconsole.googleapis.com)" on your Google API project.
+Although you can now grant your Plausible installation access to your Google account, you still will not be able to use the search console integration or data import features until you enable the "[Google Search Console API](https://console.developers.google.com/apis/api/searchconsole.googleapis.com)" and/or "[Analytics Reporting API](https://console.developers.google.com/apis/api/analyticsreporting.googleapis.com)" on your Google API project.
 
 1. Click on "Enable APIs and Services."
 
 ![google_enable_1](https://user-images.githubusercontent.com/85956139/132954489-34071ab3-dd96-44ab-83be-02431a888df9.jpg)
 
-2. Search for "Google Search Console API" in the search bar of the API Library.
+2. Search for "Google Search Console API" or "Analytics Reporting API"in the search bar of the API Library.
 
 ![google_enable2](https://user-images.githubusercontent.com/85956139/132954499-bc96eb44-d94b-4413-8e0e-c2008fc60242.png)
 
-3. Click on "Google Search Console API" and the button to enable.
+3. Click on the API and enable it.
 
 ![google_enable3](https://user-images.githubusercontent.com/85956139/132954503-df8caff9-8654-4ec0-87eb-4d76363ebc75.png)
 
 ![google_enable4](https://user-images.githubusercontent.com/85956139/132954508-290bda57-47cf-4cda-bb6d-77a1c8baa485.png)
 
+To enable Search Console integration, continue with the following 2 steps. These are not necessary if you only require support for importing data from Google Analytics.
+
 4. Finally, return to APIs & Services, and select "Domain verification". If you can't see the "Domain verification" menu item, open the navigation ("hamburger") menu in the top left corner and select "APIs & Services". "Domain verification" is a menu item below that.
 
-5. Add the same domain you used in Step 2 above. You will be prompted to go to Google Search Console to finish configuration, which coincidentally is exactly where you need to be to start the [Google Search Console Integration](google-search-console-integration.md) instructions.
+5. Add the same domain you used in task 2 above. You will be prompted to go to Google Search Console to finish configuration, which coincidentally is exactly where you need to be to start the [Google Search Console Integration](google-search-console-integration.md) instructions.
 
 :::note
 Our only source of funding is our premium, managed service for running Plausible in the cloud. If you're looking for an alternative way to support the project, we've put together some sponsorship packages. Maintaining open source software is a thankless, time-consuming job. We released our code on GitHub and made it easy to self-host on principle, not because it's good business. If you're self-hosting Plausible, [sponsoring us](https://github.com/sponsors/plausible) is a great way to give back to the community and to contribute to the long-term sustainability of the project. Thank you for supporting independent creators of Free Open Source Software!

docs/stats-api.md

@@ -20,6 +20,10 @@ The easiest way to explore the API is by using our Postman collection. Just defi
 
 [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32c111c4f6d2cccef9dd)
 
+:::note
+Any data imported from Google Analytics is not included in results returned via the Stats API.
+:::
+
 ## Concepts
 
 Querying the Plausible API will feel familiar if you have used time-series databases before. You cannot query individual records from

sidebars.js

@@ -1,7 +1,7 @@
 module.exports = {
   someSidebar: {
     "Get Started": ['introduction', 'register-account', 'add-website', 'plausible-script', 'script-extensions', 'integration-guides', 'troubleshoot-integration', 'your-plausible-experience'],
-    "Website Settings": ['website-settings', 'general', 'users-roles', 'visibility', 'shared-links', 'embed-dashboard', 'email-reports', 'traffic-spikes', 'slack-reports', 'excluding-pages', 'transfer-ownership', 'reset-site-data', 'delete-site-data', 'excluding'],
+    "Website Settings": ['website-settings', 'general', 'users-roles', 'visibility', 'shared-links', 'embed-dashboard', 'google-analytics-import', 'email-reports', 'traffic-spikes', 'slack-reports', 'excluding-pages', 'transfer-ownership', 'reset-site-data', 'delete-site-data', 'excluding'],
     "Dashboard": ['guided-tour', 'top-referrers', 'manual-link-tagging', 'google-search-console-integration', 'top-pages', 'countries', 'devices', 'filters-segments', 'export-stats', 'metrics-definitions', 'keyboard-shortcuts', 'dashboard-faq'],
     "Goal Conversions": ['goal-conversions', 'pageview-goals', 'custom-event-goals', 'outbound-link-click-tracking', 'error-pages-tracking-404'],
     "Adblockers": ['proxy/introduction',