Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kentico/xperience-google-lookerstudio
Use data from your Kentico Xperience website in Looker Studio reports.
https://github.com/kentico/xperience-google-lookerstudio
analytics google-data-studio kentico-xperience looker-studio reporting
Last synced: 6 days ago
JSON representation
Use data from your Kentico Xperience website in Looker Studio reports.
- Host: GitHub
- URL: https://github.com/kentico/xperience-google-lookerstudio
- Owner: Kentico
- License: mit
- Created: 2022-06-27T10:34:54.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-07-20T13:34:36.000Z (over 1 year ago)
- Last Synced: 2024-03-26T04:01:38.626Z (11 months ago)
- Topics: analytics, google-data-studio, kentico-xperience, looker-studio, reporting
- Language: C#
- Homepage: https://www.kentico.com
- Size: 321 KB
- Stars: 5
- Watchers: 27
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://www.nuget.org/packages/Kentico.Xperience.Libraries)
[](https://stackoverflow.com/tags/kentico)
# Xperience Looker Studio Integration
Create flexible [Looker Studio](https://cloud.google.com/looker-studio) reports which display data from your Xperience website. For example, these reports can show information about [contacts](https://docs.xperience.io/x/gQiRBg) and their [activities](https://docs.xperience.io/x/oQiRBg), [email marketing](https://docs.xperience.io/x/-QeRBg) statistics, and more. Please see our [Terms of Service](/LICENSE.md) and [Privacy Policy](/PRIVACY_POLICY.md) for more information about how your data is used.
Use the following process to set up the integration:
1. [Install](#installation) the module into your Xperience administration project.
2. [Configure exactly which types of data will be available for Looker Studio and generate the report](#generate-the-report-in-xperience).
3. To comply with personal data protection policies, [set up consents and data anonymization](#data-protection).
4. [Create Looker Studio reports and add a data source](#add-the-xperience-data-source-to-looker-studio-reports) using the *Kentico Xperience* [connector](https://support.google.com/looker-studio/answer/6318763).
## Compatibility and Prerequisites
* *Kentico Xperience 13.0.0* or newer.
* The integration works via the Xperience administration project.
* The development model used for the live site does not affect the integration, and both ASP.NET Core and MVC 5 are supported.
* Your Xperience administration project **must be publicly accessible** (not running on an internal network).
* Your application must regularly process [scheduled tasks](https://docs.xperience.io/x/Fg_RBg).
## Installation
1. Download the _Kentico.Xperience.Google.DataStudio_ ZIP package by locating the latest [Release](https://github.com/Kentico/xperience-google-lookerstudio/releases).
2. In the Xperience administration, open the **Sites** application.
3. [Import](https://docs.xperience.io/x/VAeRBg) the downloaded package.
* Make sure the **Import files** and **Import code files** [settings](https://docs.xperience.io/deploying-websites/exporting-and-importing-sites/importing-a-site-or-objects#Importingasiteorobjects-Import-Objectselectionsettings) are enabled.
4. Perform the [necessary steps](https://docs.xperience.io/deploying-websites/exporting-and-importing-sites/importing-a-site-or-objects#Importingasiteorobjects-Importingpackageswithfiles) to include the following imported folder in your project:
* `/CMSModules/Kentico.Xperience.Google.DataStudio`
## Generate the report in Xperience
To reduce the number of database queries required to display your Xperience data, the Looker Studio integration generates a physical JSON file in the _App_Data/CMSModules/Kentico.Xperience.Google.DataStudio_ directory. This file is generated by the [scheduled task](https://docs.xperience.io/x/Fg_RBg) **Generate Google Data Studio report**, which is configured to run daily by default.
To begin using the Looker Studio connector immediately after installing the integration, go to the **Scheduled tasks** application and manually execute the task.
### Configure report fields
The generated report contains certain fields by default, which you can find in [`DefaultDataStudioFieldSetProvider.cs`](/src/Kentico.Xperience.Google.DataStudio/Services/Implementations/DefaultDataStudioFieldSetProvider.cs). The report fields are defined by [`FieldSets`](/src/Kentico.Xperience.Google.DataStudio/Models/FieldSet.cs) which represent a single object type (like contacts) and its fields which are represented by a list of [`FieldDefinitions`](/src/Kentico.Xperience.Google.DataStudio/Models/FieldDefinition.cs).
If you wish to modify the default list of fields, create a custom implementation of [`IDataStudioFieldSetProvider`](/src/Kentico.Xperience.Google.DataStudio/Services/IDataStudioFieldSetProvider.cs). The class must be added under the **CMS\Old_App_Code** folder of your Xperience administration project.
Define the `GetFieldSets` method. For example, if your reports only need to display contacts and activities, you can remove the other default `FieldSets`:
```cs
[assembly: RegisterImplementation(typeof(IDataStudioFieldSetProvider), typeof(CustomFieldSetProvider), Lifestyle = Lifestyle.Singleton, Priority = RegistrationPriority.Default)]
namespace MySite.LookerStudio
{
///
/// Custom implementation of .
///
public class CustomFieldSetProvider : IDataStudioFieldSetProvider
{
public IEnumerable GetFieldSets()
{
return new FieldSet[]
{
DataStudioConstants.activityFieldSet,
DataStudioConstants.contactFieldSet
};
}
```
You can also add/remove `FieldDefinitions` from the default [`FieldSet.Fields`](/src/Kentico.Xperience.Google.DataStudio/Models/FieldSet.cs#L24) properties, or create your own custom `FieldSets`. For example, to add products to the report you can create a new `FieldSet` which contains the fields you are interested in displaying:
```cs
public IEnumerable GetFieldSets()
{
return new FieldSet[]
{
DataStudioConstants.activityFieldSet,
// Other FieldSets...
new FieldSet {
ObjectType = SKUInfo.OBJECT_TYPE_SKU,
DateFilterField = nameof(SKUInfo.SKUCreated),
Fields = new FieldDefinition[]
{
new FieldDefinition {
Name = nameof(SKUInfo.SKUID),
DataType = DataStudioFieldType.TEXT,
Anonymize = true
},
new FieldDefinition {
Name = nameof(SKUInfo.SKUCreated),
DataType = DataStudioFieldType.YEAR_MONTH_DAY_SECOND
}
}
},
};
}
```
> :bulb: When creating a new `FieldSet`, always include the `DateFilterField` if supported by the object type, and include that field in the `Fields` list. This ensures that reports can display the correct data for the selected timeframe. This field is generally the object's "created on" date - `SKUInfo.SKUCreated` for products in the example above.
## Data protection
Because the personal information of your visitors is transmitted to Google's servers, it is important to keep [GDPR](https://docs.xperience.io/x/Ng_RBg) and other data protection regulations in mind while using this integration. By default, this integration protects your visitor's data using two approaches:
- Anonymizing (hashing) identifiers
- Checking [consent](https://docs.xperience.io/x/PA_RBg) agreements
### Consents
If you are collecting data about your visitors on your website (e.g. via forms or activities), you should already have one or more [consents](https://docs.xperience.io/x/PA_RBg) active. We recommend creating another consent which notifies visitors that their data may be sent to Google for reporting purposes. This integration will automatically remove contacts and their activities from the report if they have not agreed to this consent.
To configure the consent requirements for the Looker Studio integration:
1. Prepare a suitable consent in the Xperience **Data protection** application, and provide a way for visitors to give agreements.
2. Open the **Settings** application.
3. Navigate to **Integration → Google Data Studio**.
4. Select your consent in the **Required consent** setting.
* The default value "(none)" means the integration will not check consent agreements and _all_ contacts/activities will appear in the report.
* If you select a consent from the list, only the data of contacts who agreed to that consent will appear in the report.
5. Click **Save**.
### Anonymization
By default, the Looker Studio integration will anonymize the IDs of all data records, such as a contact's ID. When the report is generated, the IDs will be hashed using a salt that is discarded after the report is finished generating. This ensures that a record in the report cannot be correlated to any specific record in your database.
If you are creating your own `FieldDefinitions`, we recommend setting `Anonymize` to _true_ for any field containing an ID:
```cs
new FieldDefinition {
Name = nameof(ContactInfo.ContactID),
DataType = DataStudioFieldType.TEXT,
Anonymize = true
}
```
### Customize data protection
If additional functionality is required to protect your visitor's data, it can be implemented by your developers. Aside from [customizing the fields in the report](#configure-report-fields), you can also implement your own anonymization method and limit the data in the report. Create a custom implementation of [`IDataStudioDataProtectionService`](/src/Kentico.Xperience.Google.DataStudio/Services/IDataStudioDataProtectionService.cs) under the **CMS\Old_App_Code** folder of your Xperience administration project:
```cs
[assembly: RegisterImplementation(typeof(IDataStudioDataProtectionService), typeof(CustomDataProtectionService), Lifestyle = Lifestyle.Singleton, Priority = RegistrationPriority.Default)]
namespace MySite.LookerStudio
{
///
/// Custom implementation of .
///
public class CustomDataProtectionService : IDataStudioDataProtectionService {
```
## Add the Xperience data source to Looker Studio reports
When creating a [new](https://datastudio.google.com/) Looker Studio report or adding a data source to an existing report, choose the **Kentico Xperience** [connector](https://support.google.com/looker-studio/answer/6318763).
Once you authorize the connector, you will be asked to provide the following:
* A **Path** which is the absolute URL of your Xperience administration website, e.g. _https://myadmin.com_.
* The username and password of an Xperience user to authenticate all Looker Studio requests. The permissions of this user are not checked. This requirement ensures that there are no unauthorized requests to access your report data.
> :warning: If the authentication parameters change (e.g. the user is deleted in Xperience), you must __revoke access__ to the connector and re-authenticate. You can find more information about revoking access in the [Data credentials](https://support.google.com/looker-studio/answer/6371135) article.
After you have properly authenticated, you can begin using the data source in report controls like tables. You can find more information about building reports in Google's documentation, such as the [Table reference](https://support.google.com/looker-studio/answer/7189044). One concept that we recommend you read carefully are Looker Studio's [blends](https://support.google.com/looker-studio/answer/9061420). If you are familiar with SQL, this is similar to performing a `JOIN` on multiple tables and will help you retrieve the data you need in your reports.
For example, let's say you want to display a table listing the latest form submission activities on your site with the email address of the contact that submitted the form. To accomplish this, you can create a new blend with two tables: one containing the activity data, and one containing the contact data. In the **Configure join** menu, link the "ActivityContactID" field from one table to the "ContactID" field of the other table. In the activity table, add a [filter](https://support.google.com/datastudio/answer/6291066) to load only the activities where "ActivityType" equals "bizformsubmit," then add any other dimensions you'd like to display. Once finished, it could look something like this:
> :bulb: The ContactEmail field is not available by default. If you want to follow the above example, you need to [add the field](#configure-report-fields) to your report.
## Contributing
Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for more information.
## License
Distributed under the MIT License. See [`LICENSE.md`](./LICENSE.md) for more information.
## Questions & Support
See the [Kentico home repository](https://github.com/Kentico/Home/blob/master/README.md) for more information about the products and general advice on submitting questions.