From 7130e827a82cbda0d7412dbfead1169814faee7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benedikt=20R=C3=B6tsch?= Date: Sun, 31 Dec 2023 17:41:56 +0100 Subject: [PATCH] docs: add guide to create a custom integration --- .../docs/guides/create-custom-integration.md | 118 ++++++++++++++++++ packages/docs/docs/new-structure.md | 3 +- packages/docs/sidebars.js | 1 + 3 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 packages/docs/docs/guides/create-custom-integration.md diff --git a/packages/docs/docs/guides/create-custom-integration.md b/packages/docs/docs/guides/create-custom-integration.md new file mode 100644 index 00000000..200f0973 --- /dev/null +++ b/packages/docs/docs/guides/create-custom-integration.md @@ -0,0 +1,118 @@ +--- +title: Custom (Tracking) Integration +--- + +# Creating a Custom (Tracking) Integration for Consent Manager + +This guide will help you create a custom integration for Consent Manager. We’ll use a generalized approach, providing you with the framework to integrate any third-party service. + +## Step 1: Define the Integration Configuration + +Create an `IntegrationConfig` object for your integration. This includes metadata like ID, title, category, colors, icon, privacy policy URL, and description. You can find suitable icons for your service at [Simple Icons](https://simpleicons.org/). + +```javascript +import { + createIconComponentFromSimpleIconsSvgPath, + getForegroundColor, + IntegrationConfig +} from '@consent-manager/core'; + +import { siYourService } from 'simple-icons'; // Replace with your service's icon + +export function yourServiceIntegration(options: { apiKey: string }): IntegrationConfig { + const { title, hex, path } = siYourService; + const color = `#${hex}`; + const contrastColor = getForegroundColor(color); + const Icon = createIconComponentFromSimpleIconsSvgPath(title, path); + const lang = typeof window !== 'undefined' ? window.navigator.language : 'en-US'; + + return { + id: 'your-service', + title, + category: 'Your Category', + color, + contrastColor, + Icon, + privacyPolicyUrl: `https://your-service-privacy-policy.com?hl=${lang}`, + description: 'Description of your service.', + WrapperComponent, + options: { apiKey: options.apiKey }, // Pass custom options here + }; +} +``` + +## Step 2: Initialize Service Scripts On User Consent + +The `WrapperComponent` is used to initialize the service and its code based on user consent. + +**Note:** That despite its name, it does not actually wrap your application - this is a legacy term from an earlier version of Consent Manager and may be renamed in the future. + +```javascript +import React from 'react'; +import { + createIconComponentFromSimpleIconsSvgPath, + getForegroundColor, + IntegrationConfig, + useDecision, + useIntegration +} from '@consent-manager/core'; +import { } from '@consent-manager/core'; + +let wasInitialized = false; + +const WrapperComponent: React.FC = () => { + const [isEnabled] = useDecision('your-service'); + const yourServiceConfig = useIntegration('your-service'); + + if (!yourServiceConfig || !yourServiceConfig.options) { + throw new Error('Initialization requires configuration.'); + } + + // Avoid double initialization + if (!wasInitialized && isEnabled) { + // Initialize your service here using yourServiceConfig.options + wasInitialized = true; + } + + return null; +}; + +export function yourServiceIntegration(options: { apiKey: string }): IntegrationConfig { + // ... + + return { + // ... + WrapperComponent, + }; +} +``` + +## Step 3: Add to Consent Manager Configuration + +Incorporate your custom integration into the Consent Manager configuration of your application. Here's an example: + +```javascript +import { ConsentManager } from '@consent-manager/core'; +import { yourServiceIntegration } from './your-service-integration'; + +const App = () => { + const config = { + integrations: [ + yourServiceIntegration({ apiKey: 'your-api-key' }) // Pass custom options here + ], + }; + + return ( + + {/* Your application components */} + + ); +}; +``` + +## Additional Notes + +- Ensure thorough testing, particularly in respecting user consent choices. +- Be mindful of performance, especially when loading external scripts or services. + +This guide gives you a flexible framework to integrate any third-party service with Consent Manager, ensuring your application is compliant and respectful of user consent. \ No newline at end of file diff --git a/packages/docs/docs/new-structure.md b/packages/docs/docs/new-structure.md index 8cc939dd..f2d7345d 100644 --- a/packages/docs/docs/new-structure.md +++ b/packages/docs/docs/new-structure.md @@ -4,7 +4,7 @@ * DONE - quick start - default interface with one integration * DONE - Style default interface * DONE - i18n integration of default interface (translate default interface) - * Implement your own interface (demo/example already existing? show examples?) + * DONE - Implement your own interface (demo/example already existing? show examples?) * Create a custom tracking integration * Frameworks: Basic tutorial + link to example * NextJS @@ -17,6 +17,7 @@ * @todo add another guide on how to handle tracking in single page applications (or ones that use routers) * @todo we actually need to list the config options (COMPONENETS dir????) * @todo document helper functions (getForegroundColor, createIconComponentFromSimpleIconsSvgPath) +* @todo double check that we dont have no more "cosntruction" sites * integrations * make more examples on how to track with certain integrations (for example matomo track events, page view and so on) diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js index ba1214ad..3f3f5813 100644 --- a/packages/docs/sidebars.js +++ b/packages/docs/sidebars.js @@ -4,6 +4,7 @@ module.exports = { Guides: [ 'guides/i18n', 'guides/client-side-routing', + 'guides/client-side-routing', 'guides/create-custom-interface', ], 'Core Components': [