Skip to content

Commit 0042779

Browse files
shahednassershahednasser
authored
docs: added integration docs for Bloom (#14907)
1 parent 991e61f commit 0042779

File tree

14 files changed

+320
-332
lines changed

14 files changed

+320
-332
lines changed

‎www/apps/bloom/app/features/_integrations/guides/klaviyo/page.mdx‎

Lines changed: 0 additions & 128 deletions
This file was deleted.

www/apps/bloom/app/features/_integrations/guides/cookiebot/page.mdx renamed to www/apps/bloom/app/features/integrations/guides/cookiebot/page.mdx

Lines changed: 31 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
import { InProductAction, getOsShortcut } from "docs-ui"
1+
import { InProductAction, getOsShortcut, InlineIcon } from "docs-ui"
2+
import { ArrowUpRightOnBox } from "@medusajs/icons"
23

34
export const metadata = {
45
title: `Cookiebot Integration`,
@@ -12,6 +13,17 @@ Cookiebot displays a consent banner to customers and manages their cookie prefer
1213

1314
{/* TODO: Add screenshot of Cookiebot consent banner on store */}
1415

16+
## When to Integrate Cookiebot
17+
18+
Integrate Cookiebot if you want to:
19+
20+
- Comply with privacy regulations by managing customer consent for cookies.
21+
- Display a customizable consent banner to customers.
22+
- Automatically block tracking cookies until consent is given.
23+
- Provide customers with control over their cookie preferences.
24+
25+
---
26+
1527
## Prerequisites
1628

1729
Before adding Cookiebot, you need a [Cookiebot account](https://www.cookiebot.com/) and a domain group ID.
@@ -33,9 +45,10 @@ You'll need this ID when Bloom asks for it.
3345

3446
To add Cookiebot using the <InProductAction product={"bloom"} type={"MEDUSA_AI_OPEN_PANE"} data={{ pane: "integrations" }}>Integrations</InProductAction> panel:
3547

36-
1. Open the Integrations tab by pressing <Kbd>{getOsShortcut()}</Kbd> + <Kbd>k</Kbd> and selecting "Integrations."
37-
2. Find the Cookiebot card in the available integrations.
38-
3. Click "Build" on the Cookiebot card.
48+
1. Press <Kbd>{getOsShortcut()}</Kbd> + <Kbd>k</Kbd> to open the preview tab switcher.
49+
2. Select the "Integrations" tab from the list.
50+
3. Find the Cookiebot card in the available integrations.
51+
4. Click "Build" on the Cookiebot card.
3952

4053
Bloom will start setting up Cookiebot and ask you for your configuration details.
4154

@@ -47,51 +60,32 @@ Bloom will start setting up Cookiebot and ask you for your configuration details
4760

4861
After you click "Build," Bloom asks questions to configure Cookiebot:
4962

50-
1. **What's your Cookiebot domain group ID?** - Paste the ID you copied from your Cookiebot dashboard.
51-
2. **Do you want to automatically block tracking cookies until consent is given?** - Answer "yes" to comply with GDPR and CCPA regulations.
52-
3. **Which cookie categories do you want to enable?** - List the categories you need (like "necessary, preferences, statistics, and marketing").
53-
54-
Bloom will add the Cookiebot script to your store and configure it based on your answers.
55-
56-
{/* TODO: Add screenshot of Bloom asking for domain group ID */}
57-
58-
---
59-
60-
## Enter Your Cookiebot Domain Group ID
61-
62-
When Bloom asks for your domain group ID, paste the ID you copied from your Cookiebot dashboard:
63-
64-
1. Make sure you copied just the ID value (not the full script).
65-
2. Paste it exactly as shown in your Cookiebot account.
66-
3. Bloom will add the Cookiebot script to your store with this ID.
63+
1. **Did you add your domain to Cookiebot?** This is required for the consent banner to work. You can add the test domain that Bloom shows with this question, and later change it to your live domain when you publish.
64+
2. **What is your Cookiebot domain group ID?** Paste the ID you copied from your Cookiebot dashboard.
6765

6866
<Note title="Technical Information">
6967

70-
Bloom adds the Cookiebot script to your store's header, so the consent banner appears before any tracking cookies load. This ensures compliance with privacy regulations.
68+
Bloom stores your credentials as environment variables in your store. They're never exposed in your code or logs. See [Environment Variables](../../../../developers/environment-variables/page.mdx) for more details.
7169

7270
</Note>
7371

74-
{/* TODO: Add screenshot of entering domain group ID */}
72+
Bloom will add the Cookiebot script to your store and configure it based on your answers.
73+
74+
{/* TODO: Add screenshot of Bloom asking for domain group ID */}
7575

7676
---
7777

7878
## Test Cookiebot
7979

80-
After Bloom finishes the setup, test Cookiebot in your preview store:
80+
After Bloom finishes the setup, you can test the Cookiebot integration in your store.
8181

82-
1. Open your store preview.
83-
2. Check that the consent banner appears when the page loads.
84-
3. Test the cookie preferences (accept all, reject all, customize).
85-
4. Verify that your cookie choices are saved when you reload the page.
86-
5. Check your Cookiebot dashboard to see if the test consent was recorded.
82+
The banner won't appear in the preview. Instead, click the <InlineIcon Icon={ArrowUpRightOnBox} alt="Open Store Preview" /> button in the bottom toolbar to open your store in a new tab.
8783

88-
If the banner appears and your preferences are saved correctly, Cookiebot is working.
84+
The consent banner should appear after the page loads. Test the different cookie preferences and verify that your choices are saved correctly.
8985

90-
<Note>
86+
### Customize Consent Banner
9187

92-
**Test Both Views:** Check the consent banner on desktop and mobile views to make sure it displays correctly on all devices.
93-
94-
</Note>
88+
If you want to make changes to the banner styling, you can customize it in your Cookiebot dashboard. Changes will be reflected in your store automatically since Bloom uses the same domain group ID for both preview and live environments.
9589

9690
{/* TODO: Add screenshot of consent banner on desktop and mobile */}
9791

@@ -105,14 +99,14 @@ To publish your Cookiebot integration:
10599

106100
1. Click the "Publish" button at the top right of your project.
107101
2. If you haven't published before, Bloom asks for details about your store.
108-
3. Your Cookiebot domain group ID works for both test and live environments, so you don't need to enter new credentials.
102+
3. Bloom will ask you to enter your live cookie domain group ID. You can use the same ID as your preview since Cookiebot doesn't differentiate between environments.
109103
4. Click "Publish" to make your changes live.
110104

111105
Your Cookiebot integration is now active on your live store. Customers will see the consent banner and can manage their cookie preferences.
112106

113-
<Note type="warning">
107+
<Note title="Verify Your Domain">
114108

115-
**Verify Your Domain:** After publishing, verify your live domain in your Cookiebot dashboard to ensure the integration works correctly on your production site.
109+
After publishing, verify your live domain in your Cookiebot dashboard to ensure the integration works correctly on your production site.
116110

117111
</Note>
118112

‎www/apps/bloom/app/features/integrations/guides/klaviyo/page.mdx‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
import { InProductAction, getOsShortcut } from "docs-ui"
2+
3+
export const metadata = {
4+
title: `Klaviyo Integration`,
5+
}
6+
7+
# {metadata.title}
8+
9+
Add [Klaviyo](https://www.klaviyo.com/) to build email lists and send marketing campaigns to your customers.
10+
11+
Klaviyo lets you send automated emails for abandoned carts, order confirmations, and marketing campaigns. Bloom sets it up for you in minutes.
12+
13+
{/* TODO: Add screenshot of Klaviyo email campaign dashboard */}
14+
15+
## When to Integrate Klaviyo
16+
17+
Integrate Klaviyo if you want to:
18+
19+
- Build email lists and grow your marketing audience.
20+
- Sync your products with Klaviyo for dynamic email content.
21+
- Send campaigns and automated emails from Klaviyo.
22+
23+
## Prerequisites
24+
25+
Before adding Klaviyo, you need a [Klaviyo account](https://www.klaviyo.com/) and API keys.
26+
27+
### Klaviyo Private API Key
28+
29+
Your Klaviyo Private API Key allows Bloom to send data from your store to Klaviyo. To get your Private API Key:
30+
31+
1. Log in to your Klaviyo account.
32+
2. Click your profile icon in the bottom left, then choose "Settings."
33+
3. Click "API Keys" in the left sidebar.
34+
4. Click "Create Private API Key."
35+
5. Give your key a name (like "Bloom Store") and give full access to List and Profiles.
36+
6. Copy your Private API Key.
37+
38+
### Klaviyo List ID
39+
40+
Your Klaviyo List ID is where Bloom will add subscribers from your store. To get your List ID:
41+
42+
1. In your Klaviyo dashboard, go to "Audience" > "Lists & Segments."
43+
2. Click on the list you want to use (or create a new one).
44+
3. In the URL, find the List ID (a string of letters and numbers after `/list/`). For example, if the URL is `https://www.klaviyo.com/lists/abc123`, your List ID is `abc123`.
45+
4. Copy your List ID.
46+
47+
---
48+
49+
## Add Klaviyo to Your Store
50+
51+
To add Klaviyo using the <InProductAction product={"bloom"} type={"MEDUSA_AI_OPEN_PANE"} data={{ pane: "integrations" }}>Integrations</InProductAction> panel:
52+
53+
1. Press <Kbd>{getOsShortcut()}</Kbd> + <Kbd>k</Kbd> to open the preview tab switcher.
54+
2. Select the "Integrations" tab from the list.
55+
3. Find the Klaviyo card in the available integrations.
56+
4. Click "Build" on the Klaviyo card.
57+
58+
Bloom will start setting up Klaviyo and ask you questions about which features you want to enable.
59+
60+
{/* TODO: Add screenshot of Klaviyo card with "Build" button highlighted */}
61+
62+
---
63+
64+
## Answer Bloom's Questions
65+
66+
After you click "Build," Bloom asks questions to configure Klaviyo:
67+
68+
1. **Where should the newsletter form appear?** Choose from options like footer, popup, or homepage section. Bloom may skip this question if your store already has a newsletter form.
69+
2. **Do you want to generate a product feed?** A product feed allows you to sync your products with Klaviyo for dynamic email content. Answer "yes" to enable this feature.
70+
71+
After you answer these questions, Bloom asks for your Klaviyo credentials:
72+
73+
1. **Klaviyo Private API Key:** Paste the Private API Key you copied from your Klaviyo dashboard.
74+
2. **Klaviyo List ID:** Paste the List ID where you want to add subscribers.
75+
3. **Storefront URL:** This will only be required if you enabled the product feed. It will be used for the URLs in your product feed. You should use the live URL of your store if you have it, or the preview URL if you don't.
76+
77+
After you provide this information, Bloom will complete the Klaviyo integration setup for you.
78+
79+
<Note title="Technical Information">
80+
81+
Bloom stores your Klaviyo credentials as environment variables in your store. They're never exposed in your code or logs. See [Environment Variables](../../../../developers/environment-variables/page.mdx) for more details.
82+
83+
</Note>
84+
85+
{/* TODO: Add screenshot of Bloom asking configuration questions */}
86+
87+
---
88+
89+
## Test Subscription with Klaviyo
90+
91+
After Bloom finishes the setup, test Klaviyo in your preview store:
92+
93+
1. Open your <InProductAction product={"bloom"} type={"MEDUSA_AI_OPEN_PANE"} data={{ pane: "store" }}>store</InProductAction> preview.
94+
2. Subscribe using the newsletter form.
95+
3. Check that the subscriber is added to your Klaviyo list.
96+
97+
---
98+
99+
## Add Product Feed to Klaviyo
100+
101+
If you enabled the product feed, Bloom will share the URL to that feed (for example, `https://your-store.com/product-feed?currency_code=usd&country_code=us`) in the chat after setup.
102+
103+
The product feed will include your product information for a specific currency and country. You can use this feed in Klaviyo to create dynamic email content that shows your products.
104+
105+
To add the product feed to Klaviyo:
106+
107+
1. Copy the product feed URL that Bloom shared in the chat.
108+
2. In your Klaviyo dashboard, go to "Content" > "Products"
109+
3. Click the "Add Custom Products" button.
110+
4. Click the "Add Source" button.
111+
5. In the form, enter a name for the source (like "Bloom Product Feed") and paste the product feed URL. You don't need to add username and password for the source.
112+
6. Click "Define Source" to add the product feed to Klaviyo.
113+
114+
You can now use the product feed in your Klaviyo email templates to show dynamic product content.
115+
116+
---
117+
118+
## Publish Klaviyo Integration
119+
120+
Once you've tested Klaviyo and it's working correctly, publish your store to make it live with production credentials.
121+
122+
To publish your Klaviyo integration:
123+
124+
1. Click the "Publish" button at the top right of your project.
125+
2. If you haven't published before, Bloom asks for details about your store.
126+
3. Bloom will ask you to enter your live Klaviyo credentials (Private API Key and List ID). Enter the same credentials you used for the preview since Klaviyo doesn't differentiate between environments.
127+
4. Click "Publish" to make your changes live.
128+
129+
Your Klaviyo integration is now active on your live store. You can track real customer events and send marketing campaigns.
130+
131+
{/* TODO: Add screenshot of publish dialog */}
132+
133+
### Update Product Feed URL
134+
135+
After publishing, make sure to update the product feed URL in your Klaviyo source to use your live backend URL instead of the preview URL. This ensures that your product feed continues to work correctly after publishing.
136+
137+
The backend URL is your admin URL without the `/app` path. For example, if your admin URL is `https://your-store.com/app`, your backend URL is `https://your-store.com`. Update the product feed URL in Klaviyo to `https://your-store.com/product-feed?currency_code=usd&country_code=us`.
138+
139+
---
140+
141+
## Need Help?
142+
143+
If you face any issues while adding Klaviyo to your Bloom store, [contact support or submit feedback](../../../../help-and-feedback/page.mdx).

0 commit comments

Comments
 (0)
⚡