diff --git a/website/docs/integrations/google-analytics.mdx b/website/docs/integrations/google-analytics.mdx new file mode 100644 index 000000000..8f4edb917 --- /dev/null +++ b/website/docs/integrations/google-analytics.mdx @@ -0,0 +1,82 @@ +--- +id: google-analytics +title: Google Analytics - Send feature flag analytics to Google Analytics +description: ConfigCat Google Analytics integration. This is a step-by-step guide on how to send feature flag analytics events to Google Analytics. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +## Sending feature flag evaluation analytics to Google Analytics + +Ensures that feature flag evaluations are logged into Google Analytics experiments. With this integration, you can have advanced analytics about your feature flag usages, A/B test results. + +### Setup + +1. Install the ConfigCat and Google Analytics SDKs to your application. +2. Configure the ConfigCat SDK with your ConfigCat SDK key and the Google Analytics SDK with your Google Analytics measurement ID. +3. In your code, subscribe to the `flagEvaluated` hook during the ConfigCat SDK initialization and send feature flag evaluation data to Google Analytics experiments with the `experience_impression` event name. +The only required parameter is the `exp_variant_string` that should contain the tool name (configcat), the feature flag's key and the feature flag's value. e.g. `configcat-isMyAwesomeFeatureEnabled-true` + +Code samples: + + +```js +const configCatClient = configcat.getClient("#YOUR_SDK_KEY", PollingMode.AutoPoll, { + setupHooks: (hooks) => + hooks.on('flagEvaluated', evaluationDetails => { + const variant = "configcat-" + evaluationDetails.key + "-" + evaluationDetails.value; + gtag('event', 'experience_impression', + { + 'exp_variant_string': variant, + 'variation_id': evaluationDetails.variationId + }); + }), +}); +``` + + + +```tsx + + hooks.on('flagEvaluated', evaluationDetails => { + const variant = "configcat-" + evaluationDetails.key + "-" + evaluationDetails.value; + gtag('event', 'experience_impression', + { + 'exp_variant_string': variant, + 'variation_id': evaluationDetails.variationId + }); + }), + }} +> + +``` + + + +The documentation only shows code examples to Javascript-based SDKs, but you can use this integration in other languages as well with sending an event to Google Analytics with using the Send Measurement Protocol events to Google Analytics endpoint. +You can subscribe to the FlagEvaluated hook in the ConfigCat SDK and send an Event to Google Analytics with the `experience_impression` event name and the following event properties: +1. `exp_variant_string`: the variant in a format like `XXX-YYYYYYYYY-ZZZZZZZZ` where `XXX` is the tool name (configcat), `YYYYYYYYY` is the feature flag's key and `ZZZZZZZZ` is the feature flag's value. e.g. `configcat-isMyAwesomeFeatureEnabled-true` +2. `variant_id`: the evalated feature flag's value or the variationId from the FlagEvaluated hook's EvaluationDetails +3. `user_id` (optional): in case you are using the tracking in a backend component and you use the user_id feature in Google Analytics, you have to send the `user_id` property as well to identify your user. You can use the User object's Identifier property from the FlagEvaluated hook or a value that best describes your user. + + + + +:::note +If you are using Text feature flags with long text values (e.g. JSON values), you can send the `variationId` in the `exp_variant_string` to Google Analytics instead of the `value`. +The `variationId` is a hashed version of the feature flag value and you can access the `variationId` on the ConfigCat Dashboard after turning on the _Show VariationIDs to support A/B testing_ +Product preference. +::: + +4. Deploy your application and wait for feature flag evaluations to happen so the `experience_impression` in Google Analytics could be populated. This could take up 1-2 days. + +5. Follow the Define an audience using the exp_variant_string parameter guide to define an audience so you can start using your feature flag evaluation event in Google Analytics. + +### Example audiences reports +Google Analytics Audience report diff --git a/website/sidebars.ts b/website/sidebars.ts index 01e40f687..91787225b 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -177,6 +177,7 @@ const sidebars: SidebarsConfig = { { type: 'doc', id: 'integrations/github', label: 'GitHub Action' }, { type: 'doc', id: 'integrations/jira', label: 'Jira Cloud Plugin' }, { type: 'doc', id: 'integrations/mixpanel', label: 'Mixpanel' }, + { type: 'doc', id: 'integrations/google-analytics', label: 'Google Analytics' }, { type: 'doc', id: 'integrations/monday', label: 'monday.com' }, { type: 'doc', id: 'integrations/slack', label: 'Slack' }, { type: 'doc', id: 'integrations/terraform', label: 'Terraform' }, diff --git a/website/src/pages/index.js b/website/src/pages/index.js index d8fa3b8eb..01781c9ab 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -98,6 +98,7 @@ const features = [ { url: 'integrations/terraform', title: 'Terraform' }, { url: 'integrations/amplitude', title: 'Amplitude' }, { url: 'integrations/mixpanel', title: 'Mixpanel' }, + { url: 'integrations/google-analytics', title: 'Google Analytics' }, { url: 'integrations/zoho-flow', title: 'Zoho Flow' }, { url: 'integrations/vscode', title: 'Visual Studio Code' }, { diff --git a/website/static/assets/googleanalytics/audiences.png b/website/static/assets/googleanalytics/audiences.png new file mode 100644 index 000000000..faec28c37 Binary files /dev/null and b/website/static/assets/googleanalytics/audiences.png differ diff --git a/website/versioned_docs/version-V1/integrations/google-analytics.mdx b/website/versioned_docs/version-V1/integrations/google-analytics.mdx new file mode 100644 index 000000000..8f4edb917 --- /dev/null +++ b/website/versioned_docs/version-V1/integrations/google-analytics.mdx @@ -0,0 +1,82 @@ +--- +id: google-analytics +title: Google Analytics - Send feature flag analytics to Google Analytics +description: ConfigCat Google Analytics integration. This is a step-by-step guide on how to send feature flag analytics events to Google Analytics. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +## Sending feature flag evaluation analytics to Google Analytics + +Ensures that feature flag evaluations are logged into Google Analytics experiments. With this integration, you can have advanced analytics about your feature flag usages, A/B test results. + +### Setup + +1. Install the ConfigCat and Google Analytics SDKs to your application. +2. Configure the ConfigCat SDK with your ConfigCat SDK key and the Google Analytics SDK with your Google Analytics measurement ID. +3. In your code, subscribe to the `flagEvaluated` hook during the ConfigCat SDK initialization and send feature flag evaluation data to Google Analytics experiments with the `experience_impression` event name. +The only required parameter is the `exp_variant_string` that should contain the tool name (configcat), the feature flag's key and the feature flag's value. e.g. `configcat-isMyAwesomeFeatureEnabled-true` + +Code samples: + + +```js +const configCatClient = configcat.getClient("#YOUR_SDK_KEY", PollingMode.AutoPoll, { + setupHooks: (hooks) => + hooks.on('flagEvaluated', evaluationDetails => { + const variant = "configcat-" + evaluationDetails.key + "-" + evaluationDetails.value; + gtag('event', 'experience_impression', + { + 'exp_variant_string': variant, + 'variation_id': evaluationDetails.variationId + }); + }), +}); +``` + + + +```tsx + + hooks.on('flagEvaluated', evaluationDetails => { + const variant = "configcat-" + evaluationDetails.key + "-" + evaluationDetails.value; + gtag('event', 'experience_impression', + { + 'exp_variant_string': variant, + 'variation_id': evaluationDetails.variationId + }); + }), + }} +> + +``` + + + +The documentation only shows code examples to Javascript-based SDKs, but you can use this integration in other languages as well with sending an event to Google Analytics with using the Send Measurement Protocol events to Google Analytics endpoint. +You can subscribe to the FlagEvaluated hook in the ConfigCat SDK and send an Event to Google Analytics with the `experience_impression` event name and the following event properties: +1. `exp_variant_string`: the variant in a format like `XXX-YYYYYYYYY-ZZZZZZZZ` where `XXX` is the tool name (configcat), `YYYYYYYYY` is the feature flag's key and `ZZZZZZZZ` is the feature flag's value. e.g. `configcat-isMyAwesomeFeatureEnabled-true` +2. `variant_id`: the evalated feature flag's value or the variationId from the FlagEvaluated hook's EvaluationDetails +3. `user_id` (optional): in case you are using the tracking in a backend component and you use the user_id feature in Google Analytics, you have to send the `user_id` property as well to identify your user. You can use the User object's Identifier property from the FlagEvaluated hook or a value that best describes your user. + + + + +:::note +If you are using Text feature flags with long text values (e.g. JSON values), you can send the `variationId` in the `exp_variant_string` to Google Analytics instead of the `value`. +The `variationId` is a hashed version of the feature flag value and you can access the `variationId` on the ConfigCat Dashboard after turning on the _Show VariationIDs to support A/B testing_ +Product preference. +::: + +4. Deploy your application and wait for feature flag evaluations to happen so the `experience_impression` in Google Analytics could be populated. This could take up 1-2 days. + +5. Follow the Define an audience using the exp_variant_string parameter guide to define an audience so you can start using your feature flag evaluation event in Google Analytics. + +### Example audiences reports +Google Analytics Audience report diff --git a/website/versioned_sidebars/version-V1-sidebars.json b/website/versioned_sidebars/version-V1-sidebars.json index f3f6626b6..5b31555ad 100644 --- a/website/versioned_sidebars/version-V1-sidebars.json +++ b/website/versioned_sidebars/version-V1-sidebars.json @@ -208,6 +208,11 @@ "id": "integrations/mixpanel", "label": "Mixpanel" }, + { + "type": "doc", + "id": "integrations/google-analytics", + "label": "Google Analytics" + }, { "type": "doc", "id": "integrations/monday",