From 65de59795f140711c158bf44ada23d1d3b215ba6 Mon Sep 17 00:00:00 2001 From: blakehacks Date: Tue, 14 May 2024 17:08:58 -0400 Subject: [PATCH 1/6] initial segment doc --- fern/docs.yml | 2 ++ fern/docs/pages/configure-segment.mdx | 26 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+) create mode 100644 fern/docs/pages/configure-segment.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 800e7e6586..f009949bdf 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -11,6 +11,8 @@ navigation: path: ./docs/pages/enable-api-playground.mdx - page: Configure Custom Domain path: ./docs/pages/configure-custom-domain.mdx + - page: Configure Segment for a new Customer + path: ./docs/pages/configure-segment.mdx - api: FDR API Reference api-name: fdr display-errors: true diff --git a/fern/docs/pages/configure-segment.mdx b/fern/docs/pages/configure-segment.mdx new file mode 100644 index 0000000000..eeaafd63f5 --- /dev/null +++ b/fern/docs/pages/configure-segment.mdx @@ -0,0 +1,26 @@ +--- +title: How to Enable Segment for a New Customer +description: Learn about how to enable analytics collection in Segment for a customer's docs site +--- + + + ### Step 1: Navigate to Segment + Go to https://app.segment.com/buildwithfern/overview + ### Step 2: Connect Requested Analytics Destinations + Customers may request analytics in one or multiple destinations. You'll need to connect each one to the existing source (https://app.segment.com/buildwithfern/sources/build_with_fern/overview). Example destinations are Posthog, Google Analytics, and Hubspot + ### Step 2A: Configure Destinations + Each destination may require some configuration. + For Posthog: + Background: we collect our own analytics in Posthog based on all buildwithfern docs sites in addition to sending data to our customers' posthog instances. To enable this, we use Segment destination functions to route events to the customer's instance. + Step 0: Get the customer's Posthog write key and docs domain (eg hume.docs.buildwithfern.com) + Step 1: Navigate to the 'Send Pageviews to Posthog' function (https://app.segment.com/buildwithfern/functions/catalog/ifnd_6642809e38542e19d398034e/edit/code) + Step 2: Add a new entry to DESTINATION_MAP with k:v of docs_domain:posthog_write_key. For example if I want to send events on 'blake.docs.buildwithfern.com' to the Posthog instance with writekey 'abcdefg', I add 'blake.docs.buildwithfern.com': 'abcdefg' to the DESTINATION_MAP + Step 3: Test! Use the built-in test function to grab sample events and run the updated function on them. You should get an 'Output: Success' message if everything goes smoothly. Try to test with at least 1 example from the new customer's site and 1 from a different docs site. + Step 4: Save and Deploy. Once you deploy your changes will go live and the events should start populating in the customer's posthog instance. + + +## Additional configs + +- **whitelabeled**: This will remove the Fern branding from the docs site. +- **api-scrolling-disabled**: This will disable the single-page API scrolling feature. +- **seo-disabled**: This will disable the site from being indexed by search engine crawlers. From b25a742f4c6656d8201e1785c31df91641da3ac0 Mon Sep 17 00:00:00 2001 From: blakehacks Date: Tue, 14 May 2024 18:29:43 -0400 Subject: [PATCH 2/6] format --- fern/docs/pages/configure-segment.mdx | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/fern/docs/pages/configure-segment.mdx b/fern/docs/pages/configure-segment.mdx index eeaafd63f5..fc720ff0c2 100644 --- a/fern/docs/pages/configure-segment.mdx +++ b/fern/docs/pages/configure-segment.mdx @@ -4,18 +4,30 @@ description: Learn about how to enable analytics collection in Segment for a cus --- + ### Step 1: Navigate to Segment + Go to https://app.segment.com/buildwithfern/overview + ### Step 2: Connect Requested Analytics Destinations + Customers may request analytics in one or multiple destinations. You'll need to connect each one to the existing source (https://app.segment.com/buildwithfern/sources/build_with_fern/overview). Example destinations are Posthog, Google Analytics, and Hubspot - ### Step 2A: Configure Destinations + + ### Step 3: Configure Destinations Each destination may require some configuration. + For Posthog: + Background: we collect our own analytics in Posthog based on all buildwithfern docs sites in addition to sending data to our customers' posthog instances. To enable this, we use Segment destination functions to route events to the customer's instance. - Step 0: Get the customer's Posthog write key and docs domain (eg hume.docs.buildwithfern.com) + + Step 0: Get the customer's Posthog write key and docs domain (eg https://dev.hume.ai/intro) + Step 1: Navigate to the 'Send Pageviews to Posthog' function (https://app.segment.com/buildwithfern/functions/catalog/ifnd_6642809e38542e19d398034e/edit/code) + Step 2: Add a new entry to DESTINATION_MAP with k:v of docs_domain:posthog_write_key. For example if I want to send events on 'blake.docs.buildwithfern.com' to the Posthog instance with writekey 'abcdefg', I add 'blake.docs.buildwithfern.com': 'abcdefg' to the DESTINATION_MAP + Step 3: Test! Use the built-in test function to grab sample events and run the updated function on them. You should get an 'Output: Success' message if everything goes smoothly. Try to test with at least 1 example from the new customer's site and 1 from a different docs site. + Step 4: Save and Deploy. Once you deploy your changes will go live and the events should start populating in the customer's posthog instance. From 39d2fa2b00b488a67f33825da1edaca0f866bc32 Mon Sep 17 00:00:00 2001 From: blakehacks Date: Tue, 14 May 2024 18:33:24 -0400 Subject: [PATCH 3/6] cleanup --- fern/docs/pages/configure-segment.mdx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/fern/docs/pages/configure-segment.mdx b/fern/docs/pages/configure-segment.mdx index fc720ff0c2..3db41ce219 100644 --- a/fern/docs/pages/configure-segment.mdx +++ b/fern/docs/pages/configure-segment.mdx @@ -30,9 +30,3 @@ description: Learn about how to enable analytics collection in Segment for a cus Step 4: Save and Deploy. Once you deploy your changes will go live and the events should start populating in the customer's posthog instance. - -## Additional configs - -- **whitelabeled**: This will remove the Fern branding from the docs site. -- **api-scrolling-disabled**: This will disable the single-page API scrolling feature. -- **seo-disabled**: This will disable the site from being indexed by search engine crawlers. From a4d7ee67bd7e68667d79223c7fe275028f7181fd Mon Sep 17 00:00:00 2001 From: blakehacks Date: Tue, 14 May 2024 18:35:18 -0400 Subject: [PATCH 4/6] formatting --- fern/docs/pages/configure-segment.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/docs/pages/configure-segment.mdx b/fern/docs/pages/configure-segment.mdx index 3db41ce219..0e82b345be 100644 --- a/fern/docs/pages/configure-segment.mdx +++ b/fern/docs/pages/configure-segment.mdx @@ -18,7 +18,7 @@ description: Learn about how to enable analytics collection in Segment for a cus For Posthog: - Background: we collect our own analytics in Posthog based on all buildwithfern docs sites in addition to sending data to our customers' posthog instances. To enable this, we use Segment destination functions to route events to the customer's instance. + Background: we collect our own analytics in Posthog based on all buildwithfern docs sites in addition to sending data to our customers' Posthog instances. To enable this, we use Segment destination functions to route events to the customer's instance. Step 0: Get the customer's Posthog write key and docs domain (eg https://dev.hume.ai/intro) @@ -28,5 +28,5 @@ description: Learn about how to enable analytics collection in Segment for a cus Step 3: Test! Use the built-in test function to grab sample events and run the updated function on them. You should get an 'Output: Success' message if everything goes smoothly. Try to test with at least 1 example from the new customer's site and 1 from a different docs site. - Step 4: Save and Deploy. Once you deploy your changes will go live and the events should start populating in the customer's posthog instance. + Step 4: Save and Deploy. Once you deploy your changes will go live and the events should start populating in the customer's Posthog instance. From c52e6fc4110e80cd40dbf92ef2e5fdf46a8c82fb Mon Sep 17 00:00:00 2001 From: blakehacks Date: Tue, 14 May 2024 18:49:49 -0400 Subject: [PATCH 5/6] update --- fern/docs/pages/configure-segment.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/fern/docs/pages/configure-segment.mdx b/fern/docs/pages/configure-segment.mdx index 0e82b345be..6bd8a170da 100644 --- a/fern/docs/pages/configure-segment.mdx +++ b/fern/docs/pages/configure-segment.mdx @@ -11,8 +11,14 @@ description: Learn about how to enable analytics collection in Segment for a cus ### Step 2: Connect Requested Analytics Destinations - Customers may request analytics in one or multiple destinations. You'll need to connect each one to the existing source (https://app.segment.com/buildwithfern/sources/build_with_fern/overview). Example destinations are Posthog, Google Analytics, and Hubspot + Customers may request analytics in one or multiple destinations. You send data to destinations by connecting them to a source (https://app.segment.com/buildwithfern/sources/build_with_fern/overview). Example destinations are Posthog, Google Analytics, and Hubspot. + Aside: Segment limits how many instances (25) of a single destination type we can connect to a single source. To get around this, we use Segment functions which pipe the data to our own analytics instance + send it to the customer's analytics instance with HTTP requests. + + For destination where we use Segment functions you do NOT need to connect a new destination to the source, you'll simply update the destination function as described below. This is currently only configured for Posthog. + + For other destination types, simply add an instance of the destination type and follow the instructions in Segment to connect it to the customer's instance. + ### Step 3: Configure Destinations Each destination may require some configuration. From dc3ce5d0f444f3386d9813886c2c72ebe22b8419 Mon Sep 17 00:00:00 2001 From: blakehacks Date: Tue, 14 May 2024 18:50:57 -0400 Subject: [PATCH 6/6] cleanup --- fern/docs/pages/configure-segment.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/fern/docs/pages/configure-segment.mdx b/fern/docs/pages/configure-segment.mdx index 6bd8a170da..3b7db42354 100644 --- a/fern/docs/pages/configure-segment.mdx +++ b/fern/docs/pages/configure-segment.mdx @@ -20,19 +20,19 @@ description: Learn about how to enable analytics collection in Segment for a cus For other destination types, simply add an instance of the destination type and follow the instructions in Segment to connect it to the customer's instance. ### Step 3: Configure Destinations - Each destination may require some configuration. + Each destination may require some configuration: For Posthog: Background: we collect our own analytics in Posthog based on all buildwithfern docs sites in addition to sending data to our customers' Posthog instances. To enable this, we use Segment destination functions to route events to the customer's instance. - Step 0: Get the customer's Posthog write key and docs domain (eg https://dev.hume.ai/intro) + Substep 0: Get the customer's Posthog write key and docs domain (eg https://dev.hume.ai/intro) - Step 1: Navigate to the 'Send Pageviews to Posthog' function (https://app.segment.com/buildwithfern/functions/catalog/ifnd_6642809e38542e19d398034e/edit/code) + Substep 1: Navigate to the 'Send Pageviews to Posthog' function (https://app.segment.com/buildwithfern/functions/catalog/ifnd_6642809e38542e19d398034e/edit/code) - Step 2: Add a new entry to DESTINATION_MAP with k:v of docs_domain:posthog_write_key. For example if I want to send events on 'blake.docs.buildwithfern.com' to the Posthog instance with writekey 'abcdefg', I add 'blake.docs.buildwithfern.com': 'abcdefg' to the DESTINATION_MAP + Substep 2: Add a new entry to DESTINATION_MAP with k:v of docs_domain:posthog_write_key. For example if I want to send events on 'blake.docs.buildwithfern.com' to the Posthog instance with writekey 'abcdefg', I add 'blake.docs.buildwithfern.com': 'abcdefg' to the DESTINATION_MAP - Step 3: Test! Use the built-in test function to grab sample events and run the updated function on them. You should get an 'Output: Success' message if everything goes smoothly. Try to test with at least 1 example from the new customer's site and 1 from a different docs site. + Substep 3: Test! Use the built-in test function to grab sample events and run the updated function on them. You should get an 'Output: Success' message if everything goes smoothly. Try to test with at least 1 example from the new customer's site and 1 from a different docs site. - Step 4: Save and Deploy. Once you deploy your changes will go live and the events should start populating in the customer's Posthog instance. + Substep 4: Save and Deploy. Once you deploy your changes will go live and the events should start populating in the customer's Posthog instance.