Experiment to use shorter setup guides (#21862)

airbyte-webapp/src/hooks/services/Experiment/experiments.ts

@@ -12,6 +12,7 @@ export interface Experiments {
   "connector.orderOverwrite": Record<string, number>;
   "connector.frequentlyUsedDestinationIds": string[];
   "connector.form.useDatepicker": boolean;
+  "connector.shortSetupGuides": boolean;
   "authPage.rightSideUrl": string | undefined;
   "authPage.hideSelfHostedCTA": boolean;
   "authPage.signup.hideName": boolean;

airbyte-webapp/src/hooks/services/useDocumentation.ts

@@ -3,6 +3,8 @@ import { UseQueryResult, useQuery } from "react-query";
 import { useConfig } from "config";
 import { fetchDocumentation } from "core/domain/Documentation";
 
+import { useExperiment } from "./Experiment";
+
 type UseDocumentationResult = UseQueryResult<string, Error>;
 
 export const documentationKeys = {
@@ -11,9 +13,14 @@ export const documentationKeys = {
 
 const DOCS_URL = /^https:\/\/docs\.airbyte\.(io|com)/;
 
+const AVAILABLE_INAPP_DOCS = ["hubspot", "facebook-marketing"];
+
 export const useDocumentation = (documentationUrl: string): UseDocumentationResult => {
   const { integrationUrl } = useConfig();
-  const url = `${documentationUrl.replace(DOCS_URL, integrationUrl)}.md`;
+  const shortSetupGuides = useExperiment("connector.shortSetupGuides", false);
+  const docName = documentationUrl.substring(documentationUrl.lastIndexOf("/") + 1);
+  const showShortSetupGuide = shortSetupGuides && AVAILABLE_INAPP_DOCS.includes(docName);
+  const url = `${documentationUrl.replace(DOCS_URL, integrationUrl)}${showShortSetupGuide ? ".inapp.md" : ".md"}`;
 
   return useQuery(documentationKeys.text(documentationUrl), () => fetchDocumentation(url), {
     enabled: !!documentationUrl,

docs/integrations/sources/facebook-marketing.inapp.md

@@ -0,0 +1,47 @@
+## Prerequisites
+
+* A [Facebook Ad Account ID](https://www.facebook.com/business/help/1492627900875762)
+
+## Setup guide
+
+1. Click **Authenticate your account** to authorize your [Meta for Developers](https://developers.facebook.com/) account. Airbyte will authenticate the account you are already logged in to. Make sure you are logged into the right account.
+2. For **Start Date**, enter the date in the `YYYY-MM-DDTHH:mm:ssZ` format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.
+
+    :::warning
+    Insight tables are only able to pull data from 37 months. If you are syncing insight tables and your start date is older than 37 months, your sync will fail.
+    :::
+
+3. For **End Date**, enter the date in the `YYYY-MM-DDTHH:mm:ssZ` format. The data added on and before this date will be replicated. If this field is blank, Airbyte will replicate the latest data.
+4. For Account ID, enter your [Facebook Ad Account ID Number](https://www.facebook.com/business/help/1492627900875762).
+5. (Optional) Toggle the **Include Deleted** button to include data from deleted Campaigns, Ads, and AdSets.
+
+    :::info
+    The Facebook Marketing API does not have a concept of deleting records in the same way that a database does. While you can archive or delete an ad campaign, the API maintains a record of the campaign. Toggling the **Include Deleted** button lets you replicate records for campaigns or ads even if they were archived or deleted from the Facebook platform.
+    :::
+
+6. (Optional) Toggle the **Fetch Thumbnail Images** button to fetch the `thumbnail_url` and store the result in `thumbnail_data_url` for each [Ad Creative](https://developers.facebook.com/docs/marketing-api/creative/).
+7. (Optional) In the Custom Insights section, click **Add**.
+    To retrieve specific fields from Facebook Ads Insights combined with other breakdowns, you can choose which fields and breakdowns to sync.
+
+    :::warning
+    Additional streams for Facebook Marketing are dynamically created based on the specified Custom Insights. For an existing Facebook Marketing source, when you are updating or removing Custom Insights, you should also ensure that any connections syncing to these streams are either disabled or have had their source schema refreshed.
+    :::
+
+    We recommend following the Facebook Marketing [documentation](https://developers.facebook.com/docs/marketing-api/insights/breakdowns) to understand the breakdown limitations. Some fields can not be requested and many others only work when combined with specific fields. For example, the breakdown `app_id` is only supported with the `total_postbacks` field.
+
+    To configure Custom Insights:
+
+    1. For **Name**, enter a name for the insight. This will be used as the Airbyte stream name
+    2. For **Fields**, enter a list of the fields you want to pull from the Facebook Marketing API.
+    3. For **End Date**, enter the date in the `YYYY-MM-DDTHH:mm:ssZ` format. The data added on and before this date will be replicated. If this field is blank, Airbyte will replicate the latest data.
+    4. For **Breakdowns**, enter a list of the breakdowns you want to configure.
+    5. For **Start Date**, enter the date in the `YYYY-MM-DDTHH:mm:ssZ` format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.
+    6. For **Time Increment**, enter the number of days over which you want to aggregate statistics.
+
+            For example, if you set this value to 7, Airbyte will report statistics as 7-day aggregates starting from the Start Date. Suppose the start and end dates are October 1st and October 30th, then the connector will output 5 records: 01 - 06, 07 - 13, 14 - 20, 21 - 27, and 28 - 30 (3 days only).  
+    7. For **Action Breakdown**, enter a list of the action breakdowns you want to configure.
+    8. For **Custom Insights Lookback Window**, fill in the appropriate value. See [more](#facebook-marketing-attribution-reporting) on this parameter.
+    9. Click **Done**.
+8. For **Page Size of Requests**, fill in the size of the page in case pagintion kicks in. Feel free to ignore it, the default value should work in most cases.
+9. For **Insights Lookback Window**, fill in the appropriate value. See [more](#facebook-marketing-attribution-reporting) on this parameter.
+10. Click **Set up source**.

docs/integrations/sources/hubspot.inapp.md

@@ -0,0 +1,13 @@
+## Prerequisite
+
+* Access to your HubSpot account
+
+## Setup guide
+
+1. For **Start date**, enter the date in `YYYY-MM-DDTHH:mm:ssZ` format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.
+2. You can use OAuth or an API key to authenticate your HubSpot account. We recommend using OAuth for Airbyte Cloud and an API key for Airbyte Open Source.
+   * To authenticate using OAuth for Airbyte Cloud, ensure you have set the appropriate scopes for HubSpot and then click **Authenticate your HubSpot account** to sign in with HubSpot and authorize your account.
+   * To authenticate using an API key for Airbyte Open Source, select **API key** from the Authentication dropdown and enter the [API key](https://knowledge.hubspot.com/integrations/how-do-i-get-my-hubspot-api-key) for your HubSpot account. Check the [performance considerations](https://docs.airbyte.com/integrations/sources/hubspot/#performance-considerations) before using an API key.
+3. Click Set up source.
+
+For detailed information on supported sync modes, supported streams, performance considerations, refer to the full documentation for [Hubspot](https://docs.airbyte.com/integrations/sources/hubspot/).

docusaurus/docusaurus.config.js

@@ -77,6 +77,7 @@ const config = {
                     sidebarPath: require.resolve('./sidebars.js'),
                     editUrl: 'https://github.com/airbytehq/airbyte/blob/master/docs',
                     path: '../docs',
+                    exclude: ['**/*.inapp.md'],
                 },
                 blog: false,
                 theme: {

docusaurus/sidebars.js

@@ -7,6 +7,7 @@ const destinationDocs = `${connectorsDocsRoot}/destinations`;
 
 function getFilenamesInDir(prefix, dir, excludes) {
     return fs.readdirSync(dir)
+        .filter(fileName => !fileName.endsWith(".inapp.md"))
         .map(fileName => fileName.replace(".md", ""))
         .filter(fileName => excludes.indexOf(fileName.toLowerCase()) === -1)
         .map(filename => {