Add Segment app docs (#1435)

components/Apps/Apps.jsx

@@ -7,6 +7,7 @@ import Avatax from "../../static/img/apps/avatax.svg";
 import CMS from "../../static/img/apps/cms-hub.svg";
 import Notification from "../../static/img/apps/notification-hub.svg";
 import Search from "../../static/img/apps/search-hub.svg";
+import Segment from "../../static/img/apps/segment.svg";
 import s from "./apps.module.css";
 
 const Shell = ({ color, title, children, href = "" }) => {
@@ -79,6 +80,14 @@ const Apps = () => {
           <Notification />
         </Shell>
 
+        <Shell
+          color={"rgb(82, 189, 148)"}
+          title={"Twilio Segment"}
+          href={"developer/app-store/apps/segment"}
+        >
+          <Segment />
+        </Shell>
+
         {/*missing docs*/}
         {/*<Shell color={"rgb(99, 91, 255)"} title={"Stipe"}>*/}
         {/*  <Stripe />*/}

docs/developer/app-store/apps/segment.mdx

@@ -0,0 +1,98 @@
+---
+title: Twilio Segment
+sidebar_label: Twilio Segment
+sidebar_position: 6
+---
+
+import { AppMetadata } from "/components/AppMetadata/AppMetadata.jsx";
+
+<AppMetadata
+  minSaleorVersion="3.20"
+  githubUrl="https://github.com/saleor/apps/tree/main/apps/segment"
+/>
+
+This application integrates with [Twilio Segment](https://segment.com/). It tracks events occurring in Saleor and sends them to Twilio Segment.
+
+## Features
+
+- Send information about order-related events to Segment.
+- Events send to Segment have identity set to user ID or email.
+
+## Assumptions & limitations
+
+-  Currently, only order-related events are supported.  
+-  Order webhooks are asynchronous, meaning events may not be sent to Segment immediately.  
+-  The app uses the [`track` API](https://segment.com/docs/connections/sources/catalog/libraries/server/node/#track). 
+-  The app attempts to retrieve user information using the user ID or email. If that fails, it will send an anonymous ID.  
+-  The app has its webhooks initially disabled; configuring the app will activate the webhooks.  
+
+## Permissions
+
+- `MANAGE_ORDERS`
+
+## Application flow
+
+The application subscribes to the following webhooks:
+
+- `ORDER_CREATED`
+- `ORDER_CANCELLED`
+- `ORDER_FULLY_PAID`
+- `ORDER_REFUNDED`
+- `ORDER_UPDATED`
+
+For each webhook, the application will send the following information to Segment:
+
+- Order `id`
+- User information:
+    - User `id`
+    - User email
+- Channel information for the order:
+    - Channel `id`
+    - Channel slug
+    - Channel name
+- Name of the shipping method used for the order
+- Total amount of the order, including:
+    - Total gross (amount & currency)
+    - Total net (amount & currency)
+- Order number
+- All lines of the order with:
+    - Line `id`
+    - Name of [product variant](/developer/products/overview#product-and-variants)
+    - Id of [product variant](/developer/products/overview#product-and-variants)
+    - SKU of product
+
+
+Example of successful handling of `ORDER_CREATED` webhook:
+
+```mermaid
+sequenceDiagram
+    OrderCreatedWebhook->>+App: Send webhook payload
+    App-->>-AppMetadata: Fetch app configuration from metadata
+    AppMetadata-->>+App: Return configuration
+    App-->>+Segment: Use configuration & webhook payload to track event
+    Segment-->>-App: Returns success
+    App->>OrderCreatedWebhook: Returns 200 status code
+```
+
+## Pre-requisites
+
+- Create an account on [Twillo Segment](https://segment.com/).
+- Create a [source](https://segment.com/docs/partners/sources/) in the Segment Dashboard UI and note down the `writeKey` for this source.
+
+## Configuration
+
+- Paste [`writeKey`](https://segment.com/docs/connections/find-writekey/) into the main configuration form in the app and click `Save`.
+
+### Testing
+
+To test if your app is working, create an order in the Saleor Dashboard. Then, go to the Segment Dashboard; you should see the `Saleor Order Updated` event in Segment.
+
+## Troubleshooting
+
+- **Events are not showing in Segment Dashboard**
+    - Ensure you have set your `writeKey` in the app configuration screen.
+    - Trigger one of the supported events (see [application flow section](#application-flow) for more details).
+
+## Development
+
+To run the application locally, follow the [_Running Saleor Apps locally_ article](/developer/extending/apps/developing-apps/running-saleor-apps-locally).

docs/developer/extending/apps/developing-apps/app-examples.mdx

@@ -8,7 +8,6 @@ import StripeIcon from "../../../../../static/img/apps/app-payment-stripe.svg"
 import InvoiceIcon from "../../../../../static/img/apps/app-invoices.svg"
 import SlackIcon from "../../../../../static/img/apps/app-slack.svg"
 import DummyPaymentIcon from "../../../../../static/img/apps/dummy-payment-app.svg"
-import SegmentIcon from "../../../../../static/img/apps/segment.svg"
 import KlarnaIcon from "../../../../../static/img/apps/app-klarna.png"
 import TaxJarIcon from "../../../../../static/img/apps/app-taxes.svg"
 import CheckoutPricesIcon from "../../../../../static/img/apps/app-checkout.svg"
@@ -47,13 +46,6 @@ These apps were built by Saleor team using [Saleor App Template](/developer/exte
         link="https://github.com/saleor/dummy-payment-app"
         icon={<DummyPaymentIcon />}
     />
-    <CompactCard
-        name="Twilio Segment"
-        description="This example app sends Saleor events to Twilio Segment."
-        technology="Next.js"
-        link="https://github.com/saleor/example-app-segment"
-        icon={<SegmentIcon />}
-    />
     <CompactCard
         name="Slack"
         description="Example app: connect Saleor to send Slack messages."
@@ -121,4 +113,3 @@ These examples can be useful if you want to build a service without the use of t
         link="https://github.com/cozyGalvinism/saleor-app-rust-axum"
     />
 </div>
-

sidebars/app-store.js

@@ -43,6 +43,7 @@ export const appStore = [
       },
     ],
   },
+  "developer/app-store/apps/segment",
   "developer/app-store/plugins/stripe",
   { type: "html", value: "<hr/>" },
   {