diff --git a/docs/docs/third-party-integrations/cohort-synchronisation/_category_.json b/docs/docs/third-party-integrations/cohort-synchronisation/_category_.json new file mode 100644 index 000000000000..dbe49eaff77d --- /dev/null +++ b/docs/docs/third-party-integrations/cohort-synchronisation/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Cohort Synchronisation", + "position": 15 +} diff --git a/docs/docs/third-party-integrations/cohort-synchronisation/amplitude.md b/docs/docs/third-party-integrations/cohort-synchronisation/amplitude.md new file mode 100644 index 000000000000..94902f8f7175 --- /dev/null +++ b/docs/docs/third-party-integrations/cohort-synchronisation/amplitude.md @@ -0,0 +1,77 @@ +--- +title: Amplitude Cohort Synchronisation +description: Synchronise Amplitude cohorts into Flagsmith as segments +sidebar_label: Amplitude +sidebar_position: 3 +--- + +# Amplitude + +Flagsmith is available as a cohort destination in Amplitude's catalogue. Once connected, every Amplitude cohort you +synchronise appears in Flagsmith as a segment, and Amplitude keeps its members up to date for you. + +Read the [cohort synchronisation overview](/third-party-integrations/cohort-synchronisation) first for how synchronised +segments behave. + +:::tip + +Flagsmith matches cohort members to identities by identifier, so the Amplitude `user_id` must be the same value your +application uses as the Flagsmith [identity](/flagsmith-concepts/identities) identifier. + +::: + +## 1. Create a synchronisation key in Flagsmith + +1. Go to the **Segments** page in your project and click **Create Segment**. +2. Choose **Amplitude**. +3. Select the environment you want to synchronise cohorts into. +4. Create a synchronisation key: give it a name, such as "Amplitude production", and copy the key value. It is shown + only once. If the environment already has a key that you created earlier and still have, you can reuse it instead. + +![Connect Amplitude modal](/img/cohort-synchronisation/connect-amplitude-modal.png) + +## 2. Add Flagsmith as a destination in Amplitude + +1. In Amplitude, go to **Data > Catalog > Destinations** and find **Flagsmith** in the cohort destinations catalogue. +2. Give the destination a recognisable name. Including the Flagsmith environment name is a good idea, because the key + decides which environment the cohorts are synchronised into. +3. Paste your synchronisation key into the **Cohort sync api key** field. +4. Check the **Identifier Mapping**. Amplitude's **User ID** must map to the Flagsmith **Identifier**. + +![Amplitude destination catalogue showing Flagsmith](/img/cohort-synchronisation/amplitude-destination-catalogue.png) + +![Amplitude Flagsmith destination configuration](/img/cohort-synchronisation/amplitude-destination-config.png) + +:::warning The key decides the environment + +Every cohort sent to this destination is synchronised into the environment its key belongs to, and nothing in Amplitude +shows which one that is. To synchronise cohorts into a second environment, create a key there and add a second Flagsmith +destination for it. + +::: + +## 3. Synchronise a cohort + +1. In Amplitude, open the cohort you want to target and click **Target users**. +2. Select your Flagsmith destination. +3. Choose the cadence, then click **Sync**: + + - **One-Time Sync** sends the cohort's current members once. + - **Scheduled Sync** resends the membership every hour or every day. + - **Real-Time Sync** resends the membership every minute. + + Scheduled and real time syncs keep the Flagsmith segment up to date on their own. With a one-time sync, later changes + to the cohort do not reach Flagsmith until you synchronise it again. + +![Amplitude Define Cadence dialog](/img/cohort-synchronisation/amplitude-define-cadence.png) + +Shortly after the first synchronisation, a segment named after your cohort appears on the **Segments** page of your +project, ready to be used in +[segment overrides](/third-party-integrations/cohort-synchronisation#using-a-synchronised-segment). + +## Notes + +- Each cohort synchronisation you set up in Amplitude creates its own segment in Flagsmith. Synchronising the same + cohort to a second destination creates a second segment. +- If you delete a synchronised segment in Flagsmith, stop the cohort synchronisation in Amplitude as well. Otherwise + Amplitude reports the synchronisation as failing and may pause it. diff --git a/docs/docs/third-party-integrations/cohort-synchronisation/csv-import.md b/docs/docs/third-party-integrations/cohort-synchronisation/csv-import.md new file mode 100644 index 000000000000..3baa94e55adb --- /dev/null +++ b/docs/docs/third-party-integrations/cohort-synchronisation/csv-import.md @@ -0,0 +1,62 @@ +--- +title: CSV Import +description: Create a Flagsmith segment from a CSV list of identifiers +sidebar_label: CSV Import +sidebar_position: 2 +--- + +# CSV Import + +Upload a list of identifiers and Flagsmith turns it into a segment you can use to override features. Use this when the +group of users you want to target is a list you can export, such as beta signups from a spreadsheet, accounts from your +CRM, or the users named in a support ticket. + +Read the [cohort synchronisation overview](/third-party-integrations/cohort-synchronisation) first for how synchronised +segments behave. + +## Preparing your file + +Your CSV file needs one column holding the identifiers of the users you want to target. These must be the same values +your application uses to identify users with Flagsmith, otherwise the segment will not match anyone. + +Other columns are ignored, so you can upload an export without stripping it down first. Files can be up to 10 MB. + +## Creating the segment + +1. Go to the **Segments** page in your project and click **Create Segment**. +2. Choose **From a CSV list**. +3. Give the segment a name and, optionally, a description. +4. Select the environment the identities should be targeted in. +5. Drag your CSV file onto the upload area, or click **Select file** to browse for it. +6. Check the **Identifier column** that Flagsmith has picked, and change it if the identifiers are in a different + column. Untick **First row contains headers** if your file starts with data rather than column names. +7. Review the preview and the number of identifiers detected, then click **Create Segment**. + +![Creating a segment from a CSV list](/img/cohort-synchronisation/csv-create-segment.png) + +:::warning Choose the environment carefully + +The identities you upload are only targeted in the environment you select, and that choice cannot be changed later. To +target the same list in another environment, create a second segment there and upload the same file. + +::: + +## Updating the members + +Membership only changes when you upload a new file, so re-upload whenever your list has moved on. + +1. Open the segment from the **Segments** page. +2. Under **Update the list**, click **Replace file** and choose your new CSV file. +3. Confirm the identifier column and header setting, review the preview, then click **Synchronise**. + +![Re-synchronising a CSV segment](/img/cohort-synchronisation/csv-resynchronise.png) + +Each upload replaces the membership rather than adding to it. Identifiers in the new file become the members of the +segment, and any identity that is missing from it loses the segment. To add people to the segment, upload a file that +contains both the existing members and the new ones. + +## Notes + +- Rows with an empty identifier, and identifiers that appear more than once, are ignored. +- The identifiers are matched to identities exactly, so watch for stray whitespace or differences in case in your + export. diff --git a/docs/docs/third-party-integrations/cohort-synchronisation/index.md b/docs/docs/third-party-integrations/cohort-synchronisation/index.md new file mode 100644 index 000000000000..fce86504833c --- /dev/null +++ b/docs/docs/third-party-integrations/cohort-synchronisation/index.md @@ -0,0 +1,106 @@ +--- +title: Cohort Synchronisation +description: Synchronise cohorts from a CSV file or your analytics platform into Flagsmith as segments +sidebar_label: Overview +sidebar_position: 1 +--- + +# Cohort Synchronisation + +Cohort synchronisation lets you target feature flags at a group of users that you have defined outside Flagsmith. You +can upload a list of identifiers as a CSV file, or connect an analytics platform and synchronise a cohort you have +already built there. Either way, the group arrives in Flagsmith as a segment that you can use to override features. + +This is useful when membership of the group depends on data Flagsmith does not hold. You can roll out to the power users +your analytics platform has identified, run a beta with a list of customers from your CRM, or turn a feature off for the +accounts named in a support ticket. + +:::info + +Cohort synchronisation is available on paid plans. + +::: + +:::warning Synchronised segments belong to one environment + +You choose the environment when you set the segment up, and it cannot be changed afterwards. The segment has no members +in any other environment, so an override you add in, say, Production will not match anyone if the segment was +synchronised into Development. To target the same group in another environment, set the segment up again there. + +::: + +## Supported sources + +- [CSV import](/third-party-integrations/cohort-synchronisation/csv-import) +- [Amplitude](/third-party-integrations/cohort-synchronisation/amplitude) + +## Creating a synchronised segment + +Every source starts in the same place. Go to the **Segments** page in your project, click **Create Segment**, and choose +how you want to define the segment. + +![Create Segment source options](/img/cohort-synchronisation/create-segment-sources.png) + +Choosing anything other than **Manually** creates a synchronised segment, and the steps that follow depend on the source +you picked. + +## How it works + +- **Each cohort becomes a segment.** Flagsmith creates the segment when you upload your first CSV file, or when your + analytics platform sends the cohort for the first time. The segment appears on your Segments page alongside your other + segments and can be used in segment overrides in the same way. +- **The source owns the membership.** You cannot edit the segment's rules in Flagsmith. To change who belongs to it, + upload a new CSV file or change the cohort definition in your analytics platform. +- **Members are matched by identity identifier.** Each entry is matched to the Flagsmith + [identity](/flagsmith-concepts/identities) with the same identifier, so your application must identify users with the + same value that the source sends. +- **Synchronisation is scoped to one environment.** You choose the environment when you set the segment up, and members + are synchronised into that environment only. The segment will not match anyone in your other environments. +- **Updates arrive differently per source.** A connected analytics platform sends membership changes on its own + schedule, so its segments stay up to date on their own. A CSV segment changes only when you upload a new file. +- **Changes are applied in the background.** A large membership can take a few minutes to be reflected in full. + +## Synchronisation keys + +Analytics platforms authenticate with Flagsmith using a **cohort synchronisation key**. CSV uploads do not need one, +because you are already signed in to the dashboard. + +- Keys are created per environment and work for any supported analytics platform. +- The key value is shown only once, at creation. Store it securely. If you lose it, create a new key. +- You can create several keys per environment, and revoke any of them at any time from **Environment Settings > + Cohorts**. Revoking a key immediately stops the synchronisation that uses it. +- Creating and revoking keys requires the _Manage segment overrides_ permission for the environment and the _Manage + segments_ permission for the project. + +![Environment Settings Cohorts tab](/img/cohort-synchronisation/environment-settings-cohorts.png) + +## Using a synchronised segment + +Once the first synchronisation completes, the segment appears on the **Segments** page of your project, labelled with +the source it came from. + +![Segments page with a synchronised segment](/img/cohort-synchronisation/synchronised-segment-list.png) + +From there it behaves like any other segment. Click on a feature in the connected environment, go to the **Segment +Overrides** tab, and create an override for it. Identities that belong to the segment, and that your application +identifies with the same identifier, will receive the overridden flags. + +Keep in mind: + +- The segment only has members in the environment you chose when you set it up. +- Membership reflects the last synchronisation, not the current state of your data. + +## Deleting a synchronised segment + +Delete the segment from the **Segments** page like any other segment. Flagsmith removes its membership data as part of +the deletion. + +If the segment was fed by an analytics platform, stop the cohort synchronisation there as well. If the platform keeps +sending updates for a segment that no longer exists, Flagsmith rejects them, and the platform will report the +synchronisation as failing and may pause it. + +## Revoking access + +To stop all synchronisation from analytics platforms into an environment, revoke its synchronisation keys in +**Environment Settings > Cohorts**. Existing segments and their members stay in place, but no further membership updates +are accepted for a revoked key. diff --git a/docs/static/img/cohort-synchronisation/amplitude-define-cadence.png b/docs/static/img/cohort-synchronisation/amplitude-define-cadence.png new file mode 100644 index 000000000000..8de97af841bc Binary files /dev/null and b/docs/static/img/cohort-synchronisation/amplitude-define-cadence.png differ diff --git a/docs/static/img/cohort-synchronisation/amplitude-destination-catalogue.png b/docs/static/img/cohort-synchronisation/amplitude-destination-catalogue.png new file mode 100644 index 000000000000..4a1bb61718bf Binary files /dev/null and b/docs/static/img/cohort-synchronisation/amplitude-destination-catalogue.png differ diff --git a/docs/static/img/cohort-synchronisation/amplitude-destination-config.png b/docs/static/img/cohort-synchronisation/amplitude-destination-config.png new file mode 100644 index 000000000000..1e02f5fc98a4 Binary files /dev/null and b/docs/static/img/cohort-synchronisation/amplitude-destination-config.png differ diff --git a/docs/static/img/cohort-synchronisation/connect-amplitude-modal.png b/docs/static/img/cohort-synchronisation/connect-amplitude-modal.png new file mode 100644 index 000000000000..b9146f364d66 Binary files /dev/null and b/docs/static/img/cohort-synchronisation/connect-amplitude-modal.png differ diff --git a/docs/static/img/cohort-synchronisation/create-segment-sources.png b/docs/static/img/cohort-synchronisation/create-segment-sources.png new file mode 100644 index 000000000000..a7cb5e624c2c Binary files /dev/null and b/docs/static/img/cohort-synchronisation/create-segment-sources.png differ diff --git a/docs/static/img/cohort-synchronisation/csv-create-segment.png b/docs/static/img/cohort-synchronisation/csv-create-segment.png new file mode 100644 index 000000000000..b8899f8bc517 Binary files /dev/null and b/docs/static/img/cohort-synchronisation/csv-create-segment.png differ diff --git a/docs/static/img/cohort-synchronisation/csv-resynchronise.png b/docs/static/img/cohort-synchronisation/csv-resynchronise.png new file mode 100644 index 000000000000..c8b33f7383d2 Binary files /dev/null and b/docs/static/img/cohort-synchronisation/csv-resynchronise.png differ diff --git a/docs/static/img/cohort-synchronisation/environment-settings-cohorts.png b/docs/static/img/cohort-synchronisation/environment-settings-cohorts.png new file mode 100644 index 000000000000..6dfef61009e2 Binary files /dev/null and b/docs/static/img/cohort-synchronisation/environment-settings-cohorts.png differ diff --git a/docs/static/img/cohort-synchronisation/synchronised-segment-list.png b/docs/static/img/cohort-synchronisation/synchronised-segment-list.png new file mode 100644 index 000000000000..4f570edba3b4 Binary files /dev/null and b/docs/static/img/cohort-synchronisation/synchronised-segment-list.png differ diff --git a/frontend/web/components/modals/ConnectCohortProviderModal/ConnectCohortProviderModal.tsx b/frontend/web/components/modals/ConnectCohortProviderModal/ConnectCohortProviderModal.tsx index 834409f72451..e83dfa351630 100644 --- a/frontend/web/components/modals/ConnectCohortProviderModal/ConnectCohortProviderModal.tsx +++ b/frontend/web/components/modals/ConnectCohortProviderModal/ConnectCohortProviderModal.tsx @@ -15,8 +15,6 @@ import { } from './providers' import './ConnectCohortProviderModal.scss' -const SEGMENTS_DOCS_URL = 'https://docs.flagsmith.com/basic-features/segments' - type ConnectCohortProviderModalProps = { projectId: number | string provider: CohortProviderKey @@ -127,8 +125,8 @@ const ConnectCohortProviderModal: FC = ({
- - Learn about Segments + + Learn about cohort synchronisation