From 65f4cc0f0d29d217100bf432504b930c878ef3fa Mon Sep 17 00:00:00 2001 From: gitcommitshow <56937085+gitcommitshow@users.noreply.github.com> Date: Thu, 19 Dec 2024 09:58:29 +0530 Subject: [PATCH 1/6] docs: add contribution guide for device mode integration --- CONTRIBUTING.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7bb52d9b0..d013a8040a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,6 +51,135 @@ To contribute to this project, you may need to install RudderStack on your machi For any questions, concerns, or queries, you can start by asking a question on our [**Slack**](https://rudderstack.com/join-rudderstack-slack-community/) channel.

+---- +# Guide to develop your first device mode RudderStack integration + +Before diving into RudderStack integration development, it's essential to understand the [RudderStack Event Specification](https://www.rudderstack.com/docs/event-spec/standard-events/). This specification serves as the foundation for collecting data in a consistent format and then transforming data for the target destinations. In this guide, we'll focus specifically on developing a destination integration in device mode integration type. + +## Understanding integration types +RudderStack supports two primary integration modes: + +1. **Cloud Mode Integration**: Events are routed through the RudderStack data plane in this mode +2. **Device Mode Integration**: Events are sent directly from the client to the destination in this mode + +## Integration development journey + +### 1. Initial setup and configuration +First, you'll need to configure the RudderStack UI in the [`rudder-integrations-config`](https://github.com/rudderlabs/rudder-integrations-config) repository: +- Navigate to [`src/configurations/destinations`](./src/configurations/destinations) +- Add necessary configuration files for dashboard setup +- Prepare integration documentation or planning documents + +### 2. Core development steps + +#### Setting up the development environment +```bash +# Clone the repository +git clone https://github.com/rudderlabs/rudder-sdk-js +# Setup the project +npm run setup +``` + +#### Essential components +Your integration will require several key files: + +1. **Constants definition** (`/packages/analytics-js-common/src/constants/integrations`) + - Integration name + - Display name + - Directory name + +2. **Main integration code** (`packages/analytics-js-integrations/src/integrations`) + ```javascript + // index.js and browser.js structure + class TestIntegrationOne { + constructor(config, analytics, destinationInfo) { + // initialization code + } + + init() { + // SDK initialization + } + + // Core methods + isLoaded() { /**Your destination SDK is loaded successfully**/} + isReady() { /**At this point, you can start sending supported events to your destination e.g. track, identify, etc.**/ } + + // Event handling + identify(rudderElement) {} + track(rudderElement) {} + page(rudderElement) {} + alias(rudderElement) {} + group(rudderElement) {} + } + ``` + +### 3. Building and testing + +#### Build process +```bash +# For legacy build +npm run build:integration --environment INTG_NAME:TestIntegrationOne + +# For modern build +npm run build:integration:modern --environment INTG_NAME:TestIntegrationOne +``` + +#### Testing setup +1. Serve the bundle: + ```bash + npx serve dist/cdn/js-integrations + ``` +2. Configure test environment: + - Modify `public/index.html` for mock source config + - Set environment variables (WRITE_KEY, DATAPLANE_URL) + - Run `npm run start` + +### 4. Automated testing +Implement automated tests for your integration: +```bash +# Run tests for specific destination +npm run test:ts -- component --destination=my_destination +``` + +### 5. UI configuration +Two approaches for adding UI configurations: + +1. **Manual configuration** + - Add config files in `src/configurations/destinations` + - Use existing templates as reference + +2. **Automated generation** + ```bash + python3 scripts/configGenerator.py + ``` + +## Deployment and support +Once development is complete: +1. The RudderStack team will handle production deployment +2. An announcement will be made in the [Release Notes](https://www.rudderstack.com/docs/releases/) and Slack `#product-releases` channel +3. Ongoing support is available through: + - GitHub PR feedback + - [RudderStack Slack community](https://rudderstack.com/join-rudderstack-slack-community/) `#contributing-to-rudderstack` channel + +## Best practices +- Draft the integration plan document before coding +- Be judicious in choosing where you want to allow integration users to configure settings (in the control plane vs the sdk instrumentation code) +- Follow existing integration examples +- Document all configuration options +- Keep code modular and maintainable + +Building a RudderStack integration requires attention to detail and thorough testing. The RudderStack team provides support throughout the development process, ensuring your integration meets quality standards and works reliably in production. + +## References + +- [RudderStack community on Slack](https://rudderstack.com/join-rudderstack-slack-community/) +- [Recording of the community workshop to develop device mode integration](https://youtu.be/70w2ESMBPCI) +- [Guide to develop source and cloud mode destination integration](https://github.com/rudderlabs/rudder-transformer/blob/develop/CONTRIBUTING.md) +- [Recording of the community workshop to develop source and cloud mode integration](https://youtu.be/OD2vCYG-P7k) +- [RudderStack Event Specification](https://www.rudderstack.com/docs/event-spec/standard-events/) + +---- + ### We look forward to your feedback on improving this project! From ec9fc435a45a6f8cc0e2bf48b8cc278a5a62b6a5 Mon Sep 17 00:00:00 2001 From: Sai Kumar Battinoju Date: Tue, 24 Dec 2024 11:44:26 +0530 Subject: [PATCH 2/6] chore: add missing npm script --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index 694f4e9706..c9c7942dab 100644 --- a/package.json +++ b/package.json @@ -19,6 +19,7 @@ "build:modern:ci": "nx affected -t build:modern --base=$BASE_REF", "build:browser": "nx run-many -t build:browser", "build:browser:modern": "nx run-many -t build:browser:modern", + "build:npm:modern": "nx run-many -t build:npm:modern", "build:package": "nx run-many -t build:package", "build:package:modern": "nx run-many -t build:package:modern", "package": "nx run-many -t package", From 55f5841ce4340ac4d3b82a70c22a5403dcffaf5e Mon Sep 17 00:00:00 2001 From: Sai Kumar Battinoju Date: Tue, 24 Dec 2024 11:45:19 +0530 Subject: [PATCH 3/6] chore: fix typo --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d013a8040a..a11e9663e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,8 +13,7 @@ Thanks for taking the time and for your help in improving this project! ## RudderStack Contributor Agreement -To contribute to this project, we need you to sign the [**Contributor License Agreement (“CLA”)**][CLA] for the first commit you make. By agreeing to the [**CLA**][CLA] -we can add you to list of approved contributors and review the changes proposed by you. +To contribute to this project, we need you to sign the [**Contributor License Agreement (“CLA”)**][CLA] for the first commit you make. By agreeing to the [**CLA**][CLA] we can add you to list of approved contributors and review the changes proposed by you. ## Contribute to this project From 6f0612a6952c37634243ecd8d9ec514c7f68f499 Mon Sep 17 00:00:00 2001 From: Sai Kumar Battinoju Date: Tue, 24 Dec 2024 11:46:23 +0530 Subject: [PATCH 4/6] chore: fix integration development instructions in contributing guide --- CONTRIBUTING.md | 116 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 90 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a11e9663e2..4ed491ded4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,19 +27,19 @@ One way you can contribute to this project is by adding integrations of your cho ### How to build the SDK -- Look for run scripts in the `package.json` file for getting the browser minified and non-minified builds. The builds are updated in the `dist` folder of the directory. Among the others, some of the important ones are: +- Look for run scripts in the `package.json` file for getting the builds. The builds are updated in the `dist` directory of corresponding package directories. Among the others, some of the important ones are: - - `npm run build:browser`: This outputs **rudder-analytics.min.js**. - - `npm run build:npm`: This outputs **rudder-sdk-js** folder that contains the npm package contents. - - `npm run build:integration:all`: This outputs **integrations** folder that contains the integrations. + - `npm run build:browser:modern`: This outputs **dist/cdn/modern** folder that contains the CDN package contents. + - `npm run build:npm:modern`: This outputs **dist/npm/modern** folder that contains the NPM package contents. + - `npm run build:integrations`: This outputs **dist/cdn/legacy** and **dist/cdn/modern** folders that contains the integration SDKs. -> We use **rollup** to build our SDKs. The configurations for them are present in `rollup-configs` folder. - -- For adding or removing integrations, modify the imports in `index.js` under the `src/integrations` folder. +> We use **rollup** to build our SDKs. Each package directory contains the configuration for it in `rollup.config.mjs`. ## Committing -We prefer squash or rebase commits so that all changes from a branch are committed to master as a single commit. All pull requests are squashed when merged, but rebasing prior to merge gives you better control over the commit message. +Please raise a pull request from your forked repository to the `develop` branch of the main repository. + +We prefer squash commits so that all changes from a branch are committed to `develop` branch as a single commit. All pull requests are squashed when merged, but rebasing prior to merge gives you better control over the commit message. ## Installing and setting up RudderStack @@ -61,7 +61,7 @@ RudderStack supports two primary integration modes: 1. **Cloud Mode Integration**: Events are routed through the RudderStack data plane in this mode 2. **Device Mode Integration**: Events are sent directly from the client to the destination in this mode -## Integration development journey +## Device mode integration development journey ### 1. Initial setup and configuration First, you'll need to configure the RudderStack UI in the [`rudder-integrations-config`](https://github.com/rudderlabs/rudder-integrations-config) repository: @@ -69,14 +69,30 @@ First, you'll need to configure the RudderStack UI in the [`rudder-integrations- - Add necessary configuration files for dashboard setup - Prepare integration documentation or planning documents +#### UI configuration +Two approaches for adding UI configurations: + +1. **Manual configuration** + - Add config files in `src/configurations/destinations` + - Use existing templates as reference + +2. **Automated generation** + ```bash + python3 scripts/configGenerator.py + ``` + ### 2. Core development steps #### Setting up the development environment ```bash # Clone the repository git clone https://github.com/rudderlabs/rudder-sdk-js + # Setup the project npm run setup + +# To reset the project setup +npm run clean && npm cache clean --force && npm run setup ``` #### Essential components @@ -87,9 +103,13 @@ Your integration will require several key files: - Display name - Directory name +The integration and display names should be referred from the auto-generated file in `/packages/analytics-js-common/src/constants/integrations/Destinations.ts`. See the existing integrations for reference. + +The directory name is the name of the integration directory in the `packages/analytics-js-integrations/src/integrations` directory. It should not contain any special characters or spaces. + 2. **Main integration code** (`packages/analytics-js-integrations/src/integrations`) ```javascript - // index.js and browser.js structure + // browser.js structure class TestIntegrationOne { constructor(config, analytics, destinationInfo) { // initialization code @@ -112,6 +132,17 @@ Your integration will require several key files: } ``` +- `config` object contains the destination configuration settings. + - You can refer to individual configuration settings using `config.`. +- `analytics` object is the RudderStack SDK instance. + - It supports all the standard methods like `track`, `identify`, `page`, etc. along with getter methods like `getAnonymousId`, `getUserId`, etc. +- `rudderElement` object is a wrapper around the actual standard RudderStack event object. + ```json + { + "message": + } + ``` + ### 3. Building and testing #### Build process @@ -128,30 +159,63 @@ npm run build:integration:modern --environment INTG_NAME:TestIntegrationOne ```bash npx serve dist/cdn/js-integrations ``` + The bundle will be served at `http://localhost:3000`. + 2. Configure test environment: - - Modify `public/index.html` for mock source config - - Set environment variables (WRITE_KEY, DATAPLANE_URL) + - Modify `packages/analytics-js/public/index.html` to mock source configuration data and point to the local integrations bundle. + ```javascript + rudderanalytics.load(writeKey, dataPlaneUrl, { + destSDKBaseURL: 'http://localhost:3000', + getSourceConfig: () => ({ + updatedAt: new Date().toISOString(), + source: { + // Use valid values from RS dashboard + name: SOURCE_NAME, + id: SOURCE_ID, + workspaceId: WORKSPACE_ID, + writeKey: WRITE_KEY, + updatedAt: new Date().toISOString(), + config: { + statsCollection: { + errors: { + enabled: false + }, + metrics: { + enabled: false + }, + } + }, + enabled: true, + destinations: [ + { + config: { + id: 'someId', + ... add other properties as needed + }, + id: 'dummyDestinationId', + enabled: true, + deleted: false, + destinationDefinition: { + name: 'TestIntegrationOne', + displayName: 'Test Integration One', + } + } + ] + } + }) + }); + ``` + - Set environment variables (WRITE_KEY, DATAPLANE_URL) in `.env` file. - Run `npm run start` ### 4. Automated testing Implement automated tests for your integration: + ```bash -# Run tests for specific destination -npm run test:ts -- component --destination=my_destination +# Run tests for specific integration at packages/analytics-js-integrations/ +npm run test -- TestIntegrationOne/ ``` -### 5. UI configuration -Two approaches for adding UI configurations: - -1. **Manual configuration** - - Add config files in `src/configurations/destinations` - - Use existing templates as reference - -2. **Automated generation** - ```bash - python3 scripts/configGenerator.py - ``` - ## Deployment and support Once development is complete: 1. The RudderStack team will handle production deployment From ec262809db0b592e2afad05d1a59563b7e4c17ac Mon Sep 17 00:00:00 2001 From: gitcommitshow <56937085+gitcommitshow@users.noreply.github.com> Date: Tue, 24 Dec 2024 22:54:45 +0530 Subject: [PATCH 5/6] fix: add more context for the guide --- CONTRIBUTING.md | 93 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 69 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ed491ded4..8d4728eb26 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,7 @@ Thanks for taking the time and for your help in improving this project! - [**Committing**](#committing) - [**Installing and setting up RudderStack**](#installing-and-setting-up-rudderstack) - [**Getting help**](#getting-help) +- [**Guide to develop your first RudderStack integration**](#guide-to-develop-your-first-rudderstack-integration) ## RudderStack Contributor Agreement @@ -51,39 +52,40 @@ For any questions, concerns, or queries, you can start by asking a question on o

---- -# Guide to develop your first device mode RudderStack integration -Before diving into RudderStack integration development, it's essential to understand the [RudderStack Event Specification](https://www.rudderstack.com/docs/event-spec/standard-events/). This specification serves as the foundation for collecting data in a consistent format and then transforming data for the target destinations. In this guide, we'll focus specifically on developing a destination integration in device mode integration type. +# Guide to develop your first RudderStack integration -## Understanding integration types -RudderStack supports two primary integration modes: +Before diving into RudderStack integration development, it's essential to understand the [RudderStack Event Specification](https://www.rudderstack.com/docs/event-spec/standard-events/). This specification serves as the foundation for collecting data in a consistent format and then transforming data for the target destinations. -1. **Cloud Mode Integration**: Events are routed through the RudderStack data plane in this mode -2. **Device Mode Integration**: Events are sent directly from the client to the destination in this mode +## Understanding connection modes - Cloud vs Device mode +RudderStack primarily supports two [connection modes](https://www.rudderstack.com/docs/destinations/rudderstack-connection-modes) - Cloud and Device mode. The development plan is different for both modes. -## Device mode integration development journey +1. **Cloud Mode Integration**: Events are routed through the [RudderStack data plane](https://github.com/rudderlabs/rudder-server) in this mode. The [`rudder-transformer`](https://github.com/rudderlabs/rudder-transformer) is responsible to transform events data in this mode. +2. **Device Mode Integration**: Events are sent directly from the client to the destination in this mode. Depending upon the client where you are collecting events from, the respective RudderStack client SDK (e.g. `rudder-sdk-js` for the web client) is responsible to transform and deliver these events (using the destination SDK). -### 1. Initial setup and configuration -First, you'll need to configure the RudderStack UI in the [`rudder-integrations-config`](https://github.com/rudderlabs/rudder-integrations-config) repository: -- Navigate to [`src/configurations/destinations`](./src/configurations/destinations) -- Add necessary configuration files for dashboard setup -- Prepare integration documentation or planning documents +## Developing _cloud mode_ RudderStack integration +Follow the guide in [Contributing.md of the `rudder-transfomer` repo](https://github.com/rudderlabs/rudder-transformer/blob/docs-contrib-guide/CONTRIBUTING.md#building-your-first-custom-rudderStack-destination-integration) as +the `rudder-transformer` is responsible for the **cloud mode** transformation. -#### UI configuration -Two approaches for adding UI configurations: +## Developing _device mode_ RudderStack integration -1. **Manual configuration** - - Add config files in `src/configurations/destinations` - - Use existing templates as reference +In this guide, we'll focus specifically on developing a destination integration in device mode integration type. Should you choose device mode integration over cloud mode integration? Following information should help you make the decision. -2. **Automated generation** - ```bash - python3 scripts/configGenerator.py - ``` +**Benefits of _device mode_ integrations** + +* Device mode is useful when you need capabilities that can only be accessed natively via a destination's SDK, such as push notifications. +* It can also be faster and cheaper because events are delivered directly, without going through RudderStack servers. + +**Disadvantages of _device mode_ integrations** + +* Device mode integrations impact website performance negatively by adding third-party SDKs +* Makes it hard to collect **first-party** data +* Prone to ad blockers + +If _device mode_ integration does not seem suitable, go ahead with the _cloud mode_ inregration development instead and follow [this guide](https://github.com/rudderlabs/rudder-transformer/blob/docs-contrib-guide/CONTRIBUTING.md#building-your-first-custom-rudderStack-destination-integration)). -### 2. Core development steps +### Setting up the development environment -#### Setting up the development environment ```bash # Clone the repository git clone https://github.com/rudderlabs/rudder-sdk-js @@ -95,14 +97,37 @@ npm run setup npm run clean && npm cache clean --force && npm run setup ``` -#### Essential components +#### Understanding the code structure + +The repository is a monorepo, with different packages under the `packages` directory. + +* `analytics-js`: The main JavaScript SDK +* `analytics-js-integrations`: Hosts device mode integrations +* `analytics-js-plugins`: Optional features for the SDK +* `analytics-js-common`: Common code used by other packages + +**Tooling:** + +* Rollup: Bundles JavaScript code +* Babel: Transpiles code +* ESLint: Catches lint issues +* Jest: Unit test framework +* NX: Manages the monorepo and CI/CD +* Size Limit: Checks the sizes of final bundles + +### Essential components Your integration will require several key files: 1. **Constants definition** (`/packages/analytics-js-common/src/constants/integrations`) + +Start by creating a new folder in `analytics-js-common` package, under `/packages/analytics-js-common/src/constants/integrations` for the new integration (e.g., test-integration-1). +We will define few basic constants mandatorily required for all the integrations. - Integration name - Display name - Directory name +This can be done by creating a `constants.ts` with `NAME`, `DISPLAY_NAME`, and `DIR_NAME` at minimum. + The integration and display names should be referred from the auto-generated file in `/packages/analytics-js-common/src/constants/integrations/Destinations.ts`. See the existing integrations for reference. The directory name is the name of the integration directory in the `packages/analytics-js-integrations/src/integrations` directory. It should not contain any special characters or spaces. @@ -216,6 +241,26 @@ Implement automated tests for your integration: npm run test -- TestIntegrationOne/ ``` +### Configurations for the integration +In order to allow user to configure your integration via the RudderStack UI (control plane), you'll to contribute to [`rudder-integrations-config`](https://github.com/rudderlabs/rudder-integrations-config) repository as well. + +- Navigate to [`src/configurations/destinations`](./src/configurations/destinations) +- Add necessary configuration files for dashboard setup +- Prepare integration documentation or planning documents + +#### UI configuration +Two approaches for adding UI configurations: + +1. **Manual configuration** + - Add config files in `src/configurations/destinations` + - Use existing templates as reference + +2. **Automated generation** + ```bash + python3 scripts/configGenerator.py + ``` + + ## Deployment and support Once development is complete: 1. The RudderStack team will handle production deployment From 6ea9d2d53dae379347cf9eb565e3b98374479837 Mon Sep 17 00:00:00 2001 From: gitcommitshow <56937085+gitcommitshow@users.noreply.github.com> Date: Tue, 24 Dec 2024 23:50:19 +0530 Subject: [PATCH 6/6] style: edit and improve formatting --- CONTRIBUTING.md | 67 +++++++++++++++++++++++++++++++------------------ 1 file changed, 43 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d4728eb26..5355090f92 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,9 +82,9 @@ In this guide, we'll focus specifically on developing a destination integration * Makes it hard to collect **first-party** data * Prone to ad blockers -If _device mode_ integration does not seem suitable, go ahead with the _cloud mode_ inregration development instead and follow [this guide](https://github.com/rudderlabs/rudder-transformer/blob/docs-contrib-guide/CONTRIBUTING.md#building-your-first-custom-rudderStack-destination-integration)). +If _device mode_ integration does not seem suitable, go ahead with the _cloud mode_ inregration development instead and follow [this guide](https://github.com/rudderlabs/rudder-transformer/blob/docs-contrib-guide/CONTRIBUTING.md#building-your-first-custom-rudderStack-destination-integration). -### Setting up the development environment +### 1. Setting up the development environment ```bash # Clone the repository @@ -97,7 +97,7 @@ npm run setup npm run clean && npm cache clean --force && npm run setup ``` -#### Understanding the code structure +### 2. Understanding the code structure The repository is a monorepo, with different packages under the `packages` directory. @@ -115,10 +115,14 @@ The repository is a monorepo, with different packages under the `packages` direc * NX: Manages the monorepo and CI/CD * Size Limit: Checks the sizes of final bundles -### Essential components +### 3. Coding the essential components of the integration + +> Before proceeding with the next steps, we recommend drafting a document outlining the requirements of your integration and relevant resources + Your integration will require several key files: -1. **Constants definition** (`/packages/analytics-js-common/src/constants/integrations`) +**Constants definition** +> `/packages/analytics-js-common/src/constants/integrations//constants.ts` Start by creating a new folder in `analytics-js-common` package, under `/packages/analytics-js-common/src/constants/integrations` for the new integration (e.g., test-integration-1). We will define few basic constants mandatorily required for all the integrations. @@ -132,7 +136,9 @@ The integration and display names should be referred from the auto-generated fil The directory name is the name of the integration directory in the `packages/analytics-js-integrations/src/integrations` directory. It should not contain any special characters or spaces. -2. **Main integration code** (`packages/analytics-js-integrations/src/integrations`) +**Main integration code** +> `packages/analytics-js-integrations/src/integrations//browser.js` + ```javascript // browser.js structure class TestIntegrationOne { @@ -168,7 +174,7 @@ The directory name is the name of the integration directory in the `packages/ana } ``` -### 3. Building and testing +### 4. Building and testing #### Build process ```bash @@ -180,13 +186,14 @@ npm run build:integration:modern --environment INTG_NAME:TestIntegrationOne ``` #### Testing setup -1. Serve the bundle: + +a. Serve the bundle: ```bash npx serve dist/cdn/js-integrations ``` The bundle will be served at `http://localhost:3000`. -2. Configure test environment: +b. Configure test environment: - Modify `packages/analytics-js/public/index.html` to mock source configuration data and point to the local integrations bundle. ```javascript rudderanalytics.load(writeKey, dataPlaneUrl, { @@ -233,7 +240,7 @@ npm run build:integration:modern --environment INTG_NAME:TestIntegrationOne - Set environment variables (WRITE_KEY, DATAPLANE_URL) in `.env` file. - Run `npm run start` -### 4. Automated testing +### 5. Automated testing Implement automated tests for your integration: ```bash @@ -241,27 +248,39 @@ Implement automated tests for your integration: npm run test -- TestIntegrationOne/ ``` -### Configurations for the integration -In order to allow user to configure your integration via the RudderStack UI (control plane), you'll to contribute to [`rudder-integrations-config`](https://github.com/rudderlabs/rudder-integrations-config) repository as well. +### 6. Configurations for the integration (in `rudder-integrations-config` repository) -- Navigate to [`src/configurations/destinations`](./src/configurations/destinations) -- Add necessary configuration files for dashboard setup -- Prepare integration documentation or planning documents +In order to allow user to configure your integration via the RudderStack UI (control plane), you'll need to contribute to [`rudder-integrations-config`](https://github.com/rudderlabs/rudder-integrations-config) repository. -#### UI configuration -Two approaches for adding UI configurations: +Create a new folder for your integration under [`src/configurations/destinations`](https://github.com/rudderlabs/rudder-integrations-config/tree/develop/src/configurations/destinations) and then add the necessary configuration files as following. -1. **Manual configuration** - - Add config files in `src/configurations/destinations` - - Use existing templates as reference +**Two approaches for adding UI configurations:** -2. **Automated generation** +A. **Automated generation:** + Create a placeholder file by changing the values in the template available at [`src/test/configData/inputData.json`](https://github.com/rudderlabs/rudder-integrations-config/blob/develop/test/configData/inputData.json) and then run following command ```bash python3 scripts/configGenerator.py ``` +B. **Manual configuration:** + Add config files in `src/configurations/destinations` using the [existing templates](https://github.com/rudderlabs/rudder-integrations-config/blob/develop/test/configData/inputData.json) as reference. +* Define the necessary configuration fields, such as API keys or customer IDs +* `db-config.json`: Define the fields needed for the web source in this file. Field names are immutable and should be intuitive + * Include the integration's name, display name, supported sources, connection modes, and configuration fields + * Specify secret keys for secure storage +* `ui-config.json`: Specify how the fields should be presented in the RudderStack dashboard, such as text boxes or dropdowns +* `schema.json`: Define validation rules for the data, using JSON schema specification. Test data should be created for schema validation + +**Best practices of configuration management:** + +Decide which configurations should be set via the UI/dashboard and which can be passed in code to an event integration property object at the client side, following key points will help in making the decision: + + * Configurations in the UI/dashboard are meant for authentication and customizing integration behavior + * Avoid over-complicating configurations in the UI, as this can be confusing. + * Using the config via UI allows changes without needing to update app instrumentation + * Config options in the UI are generic, whereas the integration object can also customize the behavior per event -## Deployment and support +### 7. Deployment and support Once development is complete: 1. The RudderStack team will handle production deployment 2. An announcement will be made in the [Release Notes](https://www.rudderstack.com/docs/releases/) and Slack `#product-releases` channel @@ -269,7 +288,7 @@ Once development is complete: - GitHub PR feedback - [RudderStack Slack community](https://rudderstack.com/join-rudderstack-slack-community/) `#contributing-to-rudderstack` channel -## Best practices +### 8. Best practices - Draft the integration plan document before coding - Be judicious in choosing where you want to allow integration users to configure settings (in the control plane vs the sdk instrumentation code) - Follow existing integration examples @@ -288,7 +307,7 @@ Building a RudderStack integration requires attention to detail and thorough tes ---- -### We look forward to your feedback on improving this project! +We look forward to your feedback on improving this project!