# Dashboards Source: https://docs.cevoid.com/analytics/dashboards Use default and custom dashboards to monitor multiple analytics reports at once. Dashboards are collections of report panels. Each panel displays one report, so a dashboard can show several parts of your Brand Engagement data in one view. Cevoid includes default dashboards. You can also create custom dashboards by choosing the reports that should appear as panels. *** ## Dashboard structure A dashboard contains: * **Panels**: Report blocks shown on the dashboard. * **Metric tiles**: Compact panels for single-number reports. * **Charts**: Visual panels for trends and breakdowns. * **Tables**: Detailed row-based panels. * **Date range**: The time period used by the dashboard panels. * **Comparison**: Previous-period context for panels that support comparison. * **Currency picker**: The currency used for monetary dashboard data. Panels can link back to the report that powers them. *** ## Default dashboards Cevoid creates a default dashboard for each module so you can look at the most important data from the start. *** ## Custom dashboards Custom dashboards are dashboards created from selected reports. They are saved views for the report panels your team wants to monitor together. Custom dashboards can contain reports for a specific campaign, market, workflow, or performance area. Result: The dashboard displays the selected reports together as panels. *** ## Metric tiles Metric tiles show compact performance numbers for the dashboard date range. A metric tile can show: * The current value. * A comparison value when comparison is enabled on the report. Open the linked report to inspect how the metric tile is configured. *** ## Charts and tables Charts and tables show report results inside the dashboard. * Trend charts show how a metric changes over time. * Bar, donut, and list views compare grouped dimensions such as posts, widgets, profiles, or sources. * Tables show detailed rows and columns. *** ## Use dashboards with reports Dashboards display reports. Reports control the data shown in dashboard panels. * Edit the report when you need to change metrics, dimensions, filters, or visualizations. * Edit the dashboard when you need to change which report panels appear together. * Open the report from a dashboard panel when you need the full chart, table, and configuration. *** ## Troubleshoot dashboard data If a dashboard does not show the data you expect: * Check the selected date range. * Confirm the workspace has activity for that period. * Open the linked report to inspect its filters and dimensions. * If the linked report shows setup requirements, open [Setup guide](/analytics/setup-guide). If a panel is empty, the linked report is usually the fastest way to see which data configuration controls it. ## Related * [Analytics Overview](/analytics/overview) * [Reports](/analytics/reports) * [Setup guide](/analytics/setup-guide) # Export Data Source: https://docs.cevoid.com/analytics/export-data Export report data from Cevoid Analytics as CSV files. Export Data lets you take report results out of Cevoid for spreadsheet work, sharing, or deeper analysis. Exports are based on the report exactly as it is configured when you start the export. If you change a default report's metrics, dimensions, filters, date range, sorting, columns, or currency, the export uses that current state. *** ## What gets exported When you export a report, choose the scope that matches what you need: * **Everything** exports the full result set for the current query. * **Visible data** exports only what is currently visible in the report table or chart scope. Use **Everything** when you want the complete dataset for analysis. Use **Visible data** when you want the same rows or columns you are reviewing in Cevoid. *** ## Export settings Before starting a CSV export, review: * **Date range**: The selected period included in the export. * **Metrics and dimensions**: The values and groupings included in the report. * **Filters**: Any rules limiting which data is included. * **Currency**: Monetary values use the report's selected currency. * **Date format**: The date format used in the CSV file. *** ## Export a report * Open **Analytics** in Cevoid. * Open **Reports**. * Select the report you want to export. * Review the report configuration. * Start the CSV export. Result: Cevoid prepares the export in the background and notifies you when the file is ready. ## Related * [Reports](/analytics/reports) * [Dashboards](/analytics/dashboards) # MCP Source: https://docs.cevoid.com/analytics/mcp Connect Cevoid Analytics to AI clients and ask questions about your data. Cevoid MCP connects your workspace analytics to AI clients that support the Model Context Protocol. After connecting, you can ask questions about metrics, dimensions, filters, and reports directly in tools like Claude, ChatGPT, Cursor, or another MCP-compatible client. Use MCP when you want to explore your analytics conversationally instead of opening and comparing reports manually. *** ## What you can ask MCP is useful for questions like: * Which posts performed best in the last 30 days? * Which reports track Instagram performance? * What conversion metrics are available? * How did widget engagement change compared with the previous period? * Which content sources drove the most activity? The AI client can query analytics directly, inspect available metrics and dimensions, browse curated reports, and run a saved report when a preset is the best fit. *** ## How it works Cevoid's MCP server exposes Analytics tools for your workspace. Your AI client connects to Cevoid, authenticates with OAuth, and then uses the available tools to answer questions using your report data. The connection is workspace-scoped, so the AI client only works with the workspace or workspaces you authorize. *** ## Connect an AI client * Open your AI client's MCP settings. * Add the Cevoid MCP server endpoint: ```text theme={"system"} https://mcp.cevoid.com/mcp ``` * Follow your AI client's authentication flow. * Ask a question about your Cevoid Analytics data. Each AI client has its own MCP setup flow. Use your client's MCP documentation for the exact configuration steps. *** ## Technical reference The generated [MCP developer docs](/developer-docs/mcp) document the available tools, auth model, resources, rate limits, and setup details. ## Related * [Analytics Overview](/analytics/overview) * [Reports](/analytics/reports) * [MCP developer docs](/developer-docs/mcp) # Overview Source: https://docs.cevoid.com/analytics/overview Understand how Cevoid Analytics helps you measure Brand Engagement. Cevoid Analytics is the analytics area for Brand Engagement data in Cevoid. It combines workspace data with tracked storefront events so you can inspect content, profiles, widgets, social collection, and sales-related engagement in one place. Use Analytics to answer specific questions in reports, monitor key data in dashboards, or ask an AI client through MCP. *** ## What Analytics includes Cevoid includes default reports and dashboards, and you can create custom views for the data your team needs to monitor. *** ## How data is collected Analytics uses two kinds of data: * **Cevoid workspace data**: Content, profiles, widgets, labels, content sources, product tags, and connected social data. * **Tracked storefront data**: Session activity, widget interactions, post interactions, product tag clicks, orders, and revenue. Some analytics are available from workspace data alone. Conversion analytics requires session tracking and sales tracking so Cevoid can connect on-site engagement to orders. *** ## Analytics pages Build analytics queries with metrics, dimensions, filters, visualizations, tables, and exports. Monitor multiple report panels in one saved view. Connect Cevoid Analytics to AI clients and ask natural-language questions about your data. Export report data as CSV files for sharing or analysis. Complete the setup requirements that unlock richer analytics. *** ## Data availability Cevoid's new analytics data collection starts on April 30, 2026. You will not see new analytics event data before this date in the updated reports. If a report includes April 30, 2026 in the selected date range, Cevoid marks the transition date in the chart or report header. Data before that date may be incomplete because Cevoid did not previously collect the same level of rich analytics events. Analytics data can take time to appear after tracking is installed or changed. If you just enabled tracking, wait for new storefront activity before treating a report as complete. ## Related * [Reports](/analytics/reports) * [Dashboards](/analytics/dashboards) * [Setup guide](/analytics/setup-guide) * [MCP](/analytics/mcp) # Reports Source: https://docs.cevoid.com/analytics/reports Use reports to drill into Brand Engagement data and build custom analytics views. Reports are the building blocks of Cevoid Analytics. A report defines which data Cevoid should query, how the result should be grouped, and how the result should be displayed. Cevoid includes default reports. You can also create custom reports with your own metrics, dimensions, filters, and visualizations. *** ## Report structure A report contains: * **Metric**: The value the report measures, such as post clicks, widget loads, revenue, or conversion rate. * **Dimension**: The field used to group the metric, such as date, post, widget, profile, content source, product, or Instagram source. * **Filter**: A rule that limits which data is included. * **Date range**: The time period included in the report. * **Granularity**: The time grouping for date-based reports, such as day, week, month, quarter, or year. * **Comparison**: The previous period shown next to the current result. * **Currency**: The currency used for monetary metrics. * **Visualization**: The chart, table, metric tile, or list used to display the result. *** ## Open a report * Open **Analytics** in Cevoid. * Open **Reports**. * Select a report from the reports table. Result: Cevoid opens the report detail page with the current chart, table, date range, and configuration sidebar. *** ## Report data The report data section controls what the report measures. * Select **Module** to choose the analytics area for the report. * Select **Metrics** to choose the values the report calculates. * Select **Group by** to group the result by a primary dimension. * Select **Segment by** to split each group into a secondary breakdown. * Use **Filters** to limit the data included in the result. Result: Cevoid updates the report preview with the selected data configuration. When you add multiple metrics, Cevoid only shows filters that work with all selected metrics. *** ## Dimensions Dimensions are created with **Group by** and **Segment by**. * **Group by** creates the main rows, chart categories, or time axis. * **Segment by** splits each group into a second level. Examples: * Group conversion metrics by **Post** to inspect post-level conversion performance. * Group widget metrics by **Widget** to compare widget performance. * Group content metrics by **Profile** to inspect profile performance. * Group content metrics by **Content source** to see where content comes from. *** ## Date range and comparison The date range controls which events and workspace changes are included in the report. Comparison compares the selected date range with the previous period of the same length. For example, if you select the last 30 days, the comparison uses the 30 days before that. Depending on the report, comparison can show the previous value, the difference between the current and previous period, or the percentage change. For date-based reports, granularity controls how the selected period is grouped in the chart or table. *** ## Currency Reports show monetary values in the workspace's primary currency by default. Use the currency selector to view revenue, order value, and other money-based metrics in another available currency. CSV exports use the current report state, including the selected currency. *** ## Visualizations Reports can use different visualizations depending on the selected metrics and dimensions: * **Metric** for one key number with optional comparison. * **Line chart** or **Area chart** for trends over time. * **Vertical bar**, **Stacked bar**, or **Grouped bar** for comparing categories. * **Donut chart** for proportional breakdowns. * **Table** for detailed rows and columns. * **List** for ranked items. The available visualization options depend on the selected report data. Cevoid can also recommend a visualization for the current configuration. *** ## Chart and table settings Depending on the visualization, you can adjust: * Items shown in the chart. * Sorting direction. * Color mode. * How remaining items are handled. * Whether comparison values are shown. * Which table columns are included. **Show in table** keeps the chart focused while the remaining rows stay available in the table. *** ## Export report data CSV export creates a file from the current report configuration. Use it when you want to work with report results in a spreadsheet or share the underlying data outside Cevoid. For export options, date formatting, and how Cevoid handles the current report state, see [Export Data](/analytics/export-data). *** ## When a report needs setup Some metrics and dimensions need extra data before they can show complete results. For example, widget interactions need session tracking, conversion reports need session and sales tracking, and product breakdowns need product catalogue data. If Cevoid shows report requirements, open [Setup guide](/analytics/setup-guide) and complete the missing steps. ## Related * [Analytics Overview](/analytics/overview) * [Dashboards](/analytics/dashboards) * [Export Data](/analytics/export-data) * [Setup guide](/analytics/setup-guide) # Setup Guide Source: https://docs.cevoid.com/analytics/setup-guide Set up the tracking and data requirements needed for richer Cevoid Analytics. Analytics setup controls which metrics and dimensions Cevoid can calculate. Some reports work from workspace data alone. Other reports need storefront tracking, connected accounts, or product catalogue data. *** ## Report requirements When a report needs more setup or data, Cevoid shows **Report requirements** in the admin panel. Each requirement has a status: * **Completed** means Cevoid can use that requirement. * **Not completed** means the report needs more setup before the related metric or dimension is complete. Open the requirement details and follow the instructions shown there. Requirements are report-specific, so a report only shows the setup steps needed for its selected metrics and dimensions. *** ## Setup requirements Common requirements are: * **Session tracking**: Required for user behavior, widget interactions, and conversion analysis. * **Sales tracking**: Required for orders, revenue, and conversion insights. * **Instagram account**: Required for Instagram source and content-type insights. * **Product brands**: Required to break analytics down by product brand. * **Product collections**: Required to break analytics down by product collection. * **Product categories**: Required to break analytics down by product category. Session and sales tracking are the core setup steps for conversion insights. Other requirements unlock deeper breakdowns for specific reports. *** ## Session tracking Session tracking enables on-site behavior metrics. It tracks storefront sessions and widget interactions, such as widget loads, impressions, post clicks, product tag clicks, reach, and claps. When sales tracking is also enabled, session tracking connects UGC interactions to conversion analysis. Setup steps: * Open the report requirement details in Cevoid. * Make sure your consent setup allows analytics storage before expecting persistent session IDs. * Add the `ca_session` cookie to your cookie policy if your consent setup requires it. * Enable session tracking for production in the requirement instructions. * Trigger storefront activity after the setup is live. Result: Cevoid can connect widget interactions to visitor sessions and use that data in analytics reports. Session tracking requires visitor consent. If consent is not granted, events can still be sent without a persistent Cevoid session ID. *** ## Sales tracking Sales tracking enables order, revenue, and conversion metrics. It connects completed orders to on-site engagement so reports can compare sessions with UGC interaction against sessions without UGC interaction. Sales tracking is required for conversion analytics, top converting posts, top converting widgets, and revenue-related reports. Shopify setup: * Open the report requirement details in Cevoid. * Enable the Cevoid checkout web pixel for each Shopify store that should send checkout events. * Click **Check status** after enabling the web pixel to confirm that Cevoid can see checkout tracking. Non-Shopify setup: * Open the report requirement details in Cevoid. * Add the checkout script shown in the admin panel to your checkout template. * Send a purchase event when an order is completed. * Use final order data, not cart or checkout-start data. * Click **Check status** after Cevoid receives new sales data. Example purchase event shape: ```javascript theme={"system"} cevoid.trigger('purchase', { orderId: '1', orderNumber: '1', currency: 'USD', amount: 20.0, items: [ { id: '2', sku: '234' } ] }) ``` Only send one conversion event per completed order. Duplicate conversion events can inflate sales and revenue metrics. *** ## Instagram account An Instagram account enables Instagram-specific analytics, such as content collected from tags, mentions, hashtags, and Instagram post type breakdowns. Setup steps: * Connect your Instagram account in Cevoid. * Confirm that Cevoid can collect the Instagram content you want to analyze. * Wait for new or synced content to appear in your workspace. Result: Reports can include Instagram dimensions such as post type, tag, mention, and hashtag source. Use [Instagram](/integrations/instagram) for connection details. *** ## Product catalogue data Product catalogue data enables product-related breakdowns. Reports can use product brand, product collection, and product category when those fields exist in your catalogue. Setup steps: * Sync or import your product catalogue. * Confirm products include the brand, collection, or category fields you want to use. * Add product tags to posts when you want product-level UGC performance. Result: Reports can group or filter analytics by product data. Use [Product Feeds](/integrations/product-feeds) and [Products & Markets](/general/products-markets) for product setup details. *** ## Troubleshoot missing data If analytics data is missing or incomplete: * Check whether the report shows setup requirements. * Confirm the date range includes activity after tracking was enabled. * Wait for new storefront activity after changing tracking settings. * For session metrics, confirm `enableSessionTracking` is enabled and consent is granted. * For sales metrics, confirm purchase events or the Shopify web pixel are sending completed orders. * For product breakdowns, confirm product catalogue fields are populated. * For Instagram breakdowns, confirm your Instagram account is connected and synced. The requirement shown in the report points to the data source that the selected metric or dimension needs. *** ## Advanced setup Most teams should follow the instructions in the admin panel. Use the Analytics SDK and developer docs when you want full programmatic control over session tracking, event tracking, consent handling, or conversion tracking. * [Set Up Session Tracking](/developer-docs/analytics/setup-session-tracking) * [Track Sales](/developer-docs/analytics/track-sales) * [Analytics SDK Installation](/developer-docs/analytics-sdk/installation) * [Analytics Consent](/developer-docs/analytics/consent) ## Related * [Analytics Overview](/analytics/overview) * [Reports](/analytics/reports) # Authentication Source: https://docs.cevoid.com/api-reference/authentication Learn how to authenticate your API requests using API keys ## Overview Authentication is required to access all Cevoid API endpoints. The Cevoid API uses token-based authentication with API keys that you include in your request headers. ## Getting Your API Key 1. Log in to your Cevoid account 2. Navigate to **Settings** -> **Integrations** -> **API** 3. Create a new API key or copy an existing one You can find your API keys at: [https://app.cevoid.com/settings/integrations/api ](https://app.cevoid.com/settings/integrations/api) *** ## Authentication Method Include your API key in the request headers using the `x-api-key` field: ```bash theme={"system"} curl https://api.cevoid.com/v1/posts \ -H "x-api-key: {your-api-key}" ``` *** ## Security Best Practices Never commit your Cevoid API token to version control systems like GitHub. Store your API keys securely and treat them like passwords. ### Recommendations * Store API keys as environment variables * Use different API keys for development and production environments * Rotate your API keys regularly * Restrict API key access to only necessary team members *** ## Example Request Here's a complete example of an authenticated API request: ```bash theme={"system"} curl https://api.cevoid.com/v1/posts \ -H "x-api-key: sk_live_1234567890abcdef" \ -H "Content-Type: application/json" ``` If your request is properly authenticated, you'll receive a successful response with the requested data. # Error Handling Source: https://docs.cevoid.com/api-reference/errors Explore errors that the API could potentially show and how to handle them ## Overview The Cevoid API uses standard HTTP status codes to indicate the success or failure of your requests. Understanding these codes will help you build robust applications that can properly handle different scenarios. ## HTTP Status Codes ### Success * **`200`** - Successful response: The request was processed successfully ### Client Errors * **`400`** - Bad request: There was an error in your request (client-side error) * **`401`** - Unauthorized: Invalid or missing authentication credentials * **`403`** - Forbidden: The request is not allowed (insufficient permissions) * **`404`** - Not found: The requested resource does not exist ### Server Errors * **`402`** - Request failed: Valid parameters were provided, but the request failed * **`500`** - Internal server error: An error occurred on Cevoid's servers *** ## Error Types The Cevoid API returns errors with specific types to help you understand what went wrong: ### `invalid_request` Issues with your request (most common): * Missing required parameters * Invalid parameter values * Malformed request body * Authentication problems ### `api_error` Issues on Cevoid's side (rare): * Internal server problems * Service temporarily unavailable * Database connectivity issues *** ## Error Response Format When an error occurs, the API returns a structured error response: ```json theme={"system"} { "type": "invalid_request", "message": "The 'limit' parameter must be between 1 and 25", "documentation_url": "https://docs.cevoid.com/api-reference/errors" } ``` ### Response Fields * **`type`**: The error category (`invalid_request` or `api_error`) * **`message`**: Human-readable description of the error * **`documentation_url`**: Link to relevant documentation *** ## Common Error Scenarios ### Authentication Errors (401) ```json theme={"system"} { "type": "invalid_request", "message": "Invalid API key provided", "documentation_url": "https://docs.cevoid.com/api-reference/authentication" } ``` **Solution**: Verify your API key is correct and properly formatted in the `x-api-key` header. ### Resource Not Found (404) ```json theme={"system"} { "type": "invalid_request", "message": "Post with ID 'abc123' not found", "documentation_url": "https://docs.cevoid.com/api-reference/errors" } ``` **Solution**: Check that the resource ID exists and you have permission to access it. ### Invalid Parameters (400) ```json theme={"system"} { "type": "invalid_request", "message": "The 'limit' parameter must be between 1 and 25", "documentation_url": "https://docs.cevoid.com/api-reference/pagination" } ``` **Solution**: Review the API documentation for correct parameter values and formats. *** ## Error Handling Best Practices ### 1. Always Check Status Codes ```javascript theme={"system"} const response = await fetch('https://api.cevoid.com/v1/posts', { headers: { 'x-api-key': 'your-api-key' } }); if (!response.ok) { const error = await response.json(); console.error(`API Error (${response.status}):`, error.message); return; } const data = await response.json(); ``` ### 2. Handle Different Error Types ```javascript theme={"system"} try { const response = await makeApiRequest(); if (!response.ok) { const error = await response.json(); switch (error.type) { case 'invalid_request': // Handle client-side errors (fix request) handleClientError(error); break; case 'api_error': // Handle server-side errors (retry or alert user) handleServerError(error); break; } } } catch (networkError) { // Handle network connectivity issues handleNetworkError(networkError); } ``` ### 3. Implement Retry Logic For `api_error` types (500, 502 status codes), implement exponential backoff retry logic as these are typically temporary server issues. ```javascript theme={"system"} async function retryRequest(url, options, maxRetries = 3) { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { const response = await fetch(url, options); if (response.ok || response.status < 500) { return response; // Success or client error (don't retry) } if (attempt === maxRetries) { throw new Error(`Request failed after ${maxRetries} attempts`); } // Wait before retrying (exponential backoff) await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt - 1))); } catch (error) { if (attempt === maxRetries) throw error; } } } ``` ### 4. Log Errors for Debugging ```javascript theme={"system"} if (!response.ok) { const error = await response.json(); // Log the error with context console.error('API Request Failed:', { status: response.status, type: error.type, message: error.message, requestUrl: response.url, timestamp: new Date().toISOString() }); } ``` Never expose API keys or sensitive information in error logs or user-facing error messages. # Filtering Source: https://docs.cevoid.com/api-reference/filtering Learn how to filter API results to retrieve specific subsets of data ## Overview The Cevoid API supports filtering to help you retrieve specific subsets of data from your requests. Filters allow you to narrow down results based on criteria such as label associations, making it easier to work with targeted datasets. ## Filter Structure Filters are passed as a URL-encoded JSON string containing an array of filter objects. Each filter object must include three required fields: * **`type`**: The type of filter to apply * **`operator`**: How to combine multiple values * **`values`**: Array of IDs to filter by ### Supported Filter Types * **`label`**: Filter posts by their associated labels ### Supported Operators * **`OR`**: Returns posts matching **any** of the provided values * **`AND`**: Returns posts matching **all** of the provided values *** ## Basic Filtering ### Filter by Single Label ```bash theme={"system"} curl -G https://api.cevoid.com/v1/posts \ -H "x-api-key: {your-api-key}" \ --data-urlencode 'filter=[{"type":"label","operator":"OR","values":["507f1f77bcf86cd799439011"]}]' ``` ### Filter by Multiple Labels (OR) Returns posts that have **at least one** of the specified labels: ```bash theme={"system"} curl -G https://api.cevoid.com/v1/posts \ -H "x-api-key: {your-api-key}" \ --data-urlencode 'filter=[{"type":"label","operator":"OR","values":["507f1f77bcf86cd799439011","507f191e810c19729de860ea"]}]' ``` ### Filter by Multiple Labels (AND) Returns posts that have **all** of the specified labels: ```bash theme={"system"} curl -G https://api.cevoid.com/v1/posts \ -H "x-api-key: {your-api-key}" \ --data-urlencode 'filter=[{"type":"label","operator":"AND","values":["507f1f77bcf86cd799439011","507f191e810c19729de860ea"]}]' ``` *** ## Common Errors ### Invalid JSON Format ``` Unexpected token in JSON at position 0 ``` **Solution**: Ensure your filter is valid JSON and properly URL-encoded. ### Invalid ID Format ``` Filter value "invalid-id" is not a valid ID ``` **Solution**: All values in the filter must be valid IDs (24-character hexadecimal strings). You can obtain label IDs from your dashboard under Settings → Labels. ### Unsupported Filter Type ``` Filter type category is not supported ``` **Solution**: Currently only `label` is supported as a filter type. ### Unsupported Operator ``` Filter operator > is not supported ``` **Solution**: Only `OR` and `AND` operators are supported. ### Missing Required Fields ``` Type is required ``` ``` Operator is required ``` ``` Values is required ``` **Solution**: Each filter object must include `type`, `operator`, and `values` fields. ### Invalid Array Structure ``` Filter param needs to be an array ``` **Solution**: The filter parameter must be a JSON array, even if you're only filtering by one label. ``` Filter values must be an array ``` **Solution**: The `values` field must be an array of IDs. *** ## Filter Best Practices ### Getting Label IDs To use label filters, you'll need the unique ID for each label: 1. Log in to your Cevoid account 2. Navigate to **Settings** → **Labels** 3. Find the label you want to filter by 4. Copy the label ID (shown as a 24-character string) You can find your labels at: [https://app.cevoid.com/settings/labels ](https://app.cevoid.com/settings/labels) ### Important Considerations Always URL-encode your filter parameter when making requests. Invalid JSON format or incorrectly formatted IDs will result in 400 errors. # Get inbox posts Source: https://docs.cevoid.com/api-reference/inbox/get-inbox-posts https://api.cevoid.com/v1/openapi.json get /v1/inbox Retrieve pending posts awaiting moderation (inbox). Each post includes the email of the member who submitted it in the uploadedBy field. # Includes Source: https://docs.cevoid.com/api-reference/includes Include related data in API responses ## Overview Use the `include` query parameter when you need related data alongside the resources you request. This lets you get that data in the same response and keep responses smaller when you do not need it. Each endpoint's API reference lists the relationships it supports and the fields they add. Includes are only available on endpoints that document the `include` parameter. ## Supported routes | Endpoint | Supported includes | | --------------- | ------------------ | | `GET /v1/posts` | `labels` | ## Query format Pass `include` once, using a comma-separated list of supported relationship names. Whitespace around names is ignored; repeating a name does not duplicate the included data. Unsupported names, empty values, and repeated `include` query parameters return `400`. Use only the names listed in the endpoint's reference. ## Response behavior Includes add related data to each returned resource. They do not change which resources match your request. When you omit `include`, you get the endpoint's default response. The endpoint's response schema describes the included fields and what to expect when related data is unavailable. ## Pagination Follow the response's `next` URL to keep includes on subsequent pages. See [Pagination](pagination) for the response format. # API Reference Source: https://docs.cevoid.com/api-reference/index Public Cevoid API docs for authentication, paging, filtering, rate limits, errors, and endpoint reference. Use this section when you are calling Cevoid's public API directly. It is limited to API-specific behavior such as authentication, pagination, filtering, errors, rate limits, and the OpenAPI endpoint reference. If you are integrating the Analytics SDK, MCP, or other implementation workflows, use the [Developer Docs](/developer-docs). If you are using Cevoid in the platform UI, use the [Help Center](/help-center). *** ## Before You Call the API Learn how to send API keys with your requests. Understand request limits and retry behavior. Work through multi-page responses safely. Narrow result sets with supported filters. *** ## Error Handling Review HTTP status codes, error response format, and common failure cases. *** ## Looking for Implementation Docs? Use developer guides for Analytics SDK setup, MCP, and other implementation flows. Use product docs for platform usage and general concepts. # Get market by ID Source: https://docs.cevoid.com/api-reference/markets/get-market-by-id https://api.cevoid.com/v1/openapi.json get /v1/markets/{id} Retrieve a specific market by its ID or shortId # Get markets Source: https://docs.cevoid.com/api-reference/markets/get-markets https://api.cevoid.com/v1/openapi.json get /v1/markets Retrieve all available markets for the company # Get members Source: https://docs.cevoid.com/api-reference/members/get-members https://api.cevoid.com/v1/openapi.json get /v1/members Retrieve all members with optional pagination # Pagination Source: https://docs.cevoid.com/api-reference/pagination Understand how to work with paginated responses in the Cevoid API ## Overview Pagination is used by the Cevoid API to limit data returned in a single request, making it easier to work with large datasets. All API endpoints that return multiple items support pagination. ## Pagination Parameters ### `limit` * **Type**: Integer * **Default**: 10 items * **Maximum**: 25 items * **Description**: Controls the number of items returned per request ### `skip` * **Type**: Integer * **Default**: 0 * **Description**: Number of items to skip from the beginning of the result set *** ## Making Paginated Requests ### Basic Pagination ```bash theme={"system"} curl -G https://api.cevoid.com/v1/posts \ -H "x-api-key: {your-api-key}" \ -d skip=0 \ -d limit=10 ``` ### Pagination with Custom Parameters ```bash theme={"system"} curl -G https://api.cevoid.com/v1/posts \ -H "x-api-key: {your-api-key}" \ -d skip=5 \ -d limit=15 ``` *** ## Response Format Paginated responses include helpful metadata to navigate through the dataset: ```json theme={"system"} { "count": 30, "next": "https://api.cevoid.com/v1/posts?skip=15&limit=10", "nodes": [ { "id": "WAz8eIbvDR60rouK", // ... post data }, { "id": "XBa9fJcwES71spvL", // ... post data } // ... more items ] } ``` ### Response Fields * **`count`**: Total number of items available * **`next`**: URL for the next page of results (if available) * **`nodes`**: Array containing the requested items *** ## Pagination Best Practices Use the `next` field from the response to get the URL for the next page of results. This ensures you're using the correct parameters. ### Efficient Navigation 1. **Start with reasonable limits**: Use the default limit of 10 for most use cases 2. **Use the `next` URL**: Don't manually construct pagination URLs 3. **Handle empty results**: Check if `nodes` is empty to detect the end of results 4. **Respect rate limits**: Don't make requests too quickly when paginating through large datasets ### Example: Iterating Through All Results ```javascript theme={"system"} let skip = 0; const limit = 25; // Use maximum for efficiency let hasMoreData = true; while (hasMoreData) { const response = await fetch(`https://api.cevoid.com/v1/posts?skip=${skip}&limit=${limit}`, { headers: { 'x-api-key': 'your-api-key' } }); const data = await response.json(); // Process the current batch data.nodes.forEach(post => { // Handle each post }); // Check if there are more results hasMoreData = data.nodes.length === limit; skip += limit; } ``` Remember that the maximum limit is 25 items per request. Requests with a higher limit will be automatically capped at 25. # Get post by ID Source: https://docs.cevoid.com/api-reference/posts/get-post-by-id https://api.cevoid.com/v1/openapi.json get /v1/posts/{id} Retrieve a single post by its ID # Get posts from a specific gallery Source: https://docs.cevoid.com/api-reference/posts/get-posts-from-a-specific-gallery https://api.cevoid.com/v1/openapi.json get /v1/galleries/{id}/posts Retrieve all posts belonging to a specific gallery # Get posts from a specific member Source: https://docs.cevoid.com/api-reference/posts/get-posts-from-a-specific-member https://api.cevoid.com/v1/openapi.json get /v1/members/{id}/posts Retrieve all posts created by a specific member # Get posts in a collection by ID Source: https://docs.cevoid.com/api-reference/posts/get-posts-in-a-collection-by-id https://api.cevoid.com/v1/openapi.json get /v1/collections/{id}/posts Retrieve posts that contain products in the specified collection (e.g. Shopify collection handle or external ID) # Get posts tagged with a specific product Source: https://docs.cevoid.com/api-reference/posts/get-posts-tagged-with-a-specific-product https://api.cevoid.com/v1/openapi.json get /v1/products/{id}/posts Retrieve all posts that have been tagged with a specific product # Get posts with a specific label Source: https://docs.cevoid.com/api-reference/posts/get-posts-with-a-specific-label https://api.cevoid.com/v1/openapi.json get /v1/labels/{id}/posts Retrieve all posts that have been assigned a specific label # List posts Source: https://docs.cevoid.com/api-reference/posts/list-posts https://api.cevoid.com/v1/openapi.json get /v1/posts Returns approved posts with optional label filtering and label details. # Rate Limits Source: https://docs.cevoid.com/api-reference/rate-limits Learn about API rate limits and how to handle them gracefully ## Overview To ensure fair usage and maintain API stability for all users, the Cevoid API enforces rate limits on certain endpoints. When you exceed the rate limit, the API returns a `429 Too Many Requests` response. *** ## Default Rate Limit The default rate limit is **5 requests per second** for most endpoints. Some endpoints may have different limits based on their resource requirements. Need a higher rate limit? [Contact support](mailto:support@cevoid.com) to discuss your requirements. *** ## Rate Limit Headers Every API response includes headers that help you monitor your usage. These headers follow the **IETF RateLimit header fields** standard: | Header | Description | | --------------------- | --------------------------------------------------------------------- | | `RateLimit-Limit` | Maximum number of requests allowed within the current window | | `RateLimit-Remaining` | Number of requests you have left in the current window | | `RateLimit-Reset` | Seconds until the rate limit resets | | `retry-after` | Seconds to wait before making another request (only on 429 responses) | *** ## Handling Rate Limit Errors When you exceed the rate limit, you'll receive a `429` status code: ```json theme={"system"} { "error": "Rate limit exceeded. Try again in 1 second." } ``` The `retry-after` header tells you exactly how long to wait before retrying. *** ## Best Practices ### 1. Monitor Rate Limit Headers Check the `RateLimit-Remaining` header to avoid RateLimit-Resetit: ```javascript theme={"system"} const response = await fetch('https://api.cevoid.com/v1/posts', { headers: { 'x-api-key': 'your-api-key' } }); const remaining = response.headers.get('RateLimit-Remaining'); const reset = response.headers.get('RateLimit-Reset'); if (parseInt(remaining) < 2) { console.log(`Low on requests. Resets in ${reset} seconds.`); } ``` ### 2. Implement Retry Logic Handle rate limit errors gracefully with exponential backoff: ```javascript theme={"system"} async function fetchWithRetry(url, options, maxRetries = 3) { for (let attempt = 1; attempt <= maxRetries; attempt++) { const response = await fetch(url, options); if (response.status === 429) { const retryAfter = parseInt(response.headers.get('retry-after') || '1'); console.log(`Rate limited. Retrying in ${retryAfter} seconds...`); await new Promise(resolve => setTimeout(resolve, retryAfter * 1000)); continue; } return response; } throw new Error('Max retries exceeded'); } ``` ### 3. Use Caching Reduce API calls by caching responses when possible: ```javascript theme={"system"} const cache = new Map(); const CACHE_TTL = 60000; // 1 minute async function getCachedPosts(galleryId) { const cacheKey = `posts-${galleryId}`; const cached = cache.get(cacheKey); if (cached && Date.now() - cached.timestamp < CACHE_TTL) { return cached.data; } const response = await fetch(`https://api.cevoid.com/v1/posts?galleryId=${galleryId}`, { headers: { 'x-api-key': 'your-api-key' } }); const data = await response.json(); cache.set(cacheKey, { data, timestamp: Date.now() }); return data; } ``` *** Rate limits are applied per API key. Sharing an API key across multiple applications will result in shared rate limits. # SDK API Source: https://docs.cevoid.com/developer-docs/analytics-sdk/api Reference the public Cevoid Analytics SDK methods for initialization, tracking, identity, and resets. Use this page when you already know you need the Cevoid Analytics SDK and want the exact public method surface. If you are still deciding between automatic widget behavior, browser-event forwarding, or manual tracking, start with [Overview](/developer-docs/analytics). Public SDK payload fields use `camelCase`. The SDK normalizes them to the internal `snake_case` telemetry format before sending events to the backend. ## `init(config)` Initializes the SDK. Call it once before your first tracking method. Repeated calls after the first successful initialization are ignored. | Option | Type | Default | Description | | ----------------------- | --------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `publishableKey` | `string` | — | Required workspace publishable key. | | `enableSessionTracking` | `boolean` | `false` | Enables Cevoid-managed session tracking after consent checks pass. | | `cookieDomain` | `string` | — | Sets the domain for the `ca_session` cookie. | | `emitBrowserEvents` | `boolean` | `true` | Emits browser [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)s such as `cevoid:post.click`. | | `apiHost` | `string` | `https://telemetry.cevoid.com` | Overrides the telemetry host. | If `enableSessionTracking` is `true`, tracked events are deferred until consent resolution completes. ## `trackEvent(name, data)` Tracks a supported Cevoid UGC widget event. ```ts theme={"system"} import { trackEvent } from '@cevoid/analytics-sdk' trackEvent('post.click', { widgetId: 'gallery-homepage', widgetType: 'gallery', postId: 'post_123', postPosition: 4, taggedProductIds: ['prod_1', 'prod_2'] }) ``` Use [`trackEvent()`](/developer-docs/analytics-sdk/api#trackeventname-data) for custom storefront implementations that need to send supported Cevoid event names manually. Supported event names: * [`widget.load`](/developer-docs/analytics-sdk/events/widget-load) * [`widget.view`](/developer-docs/analytics-sdk/events/widget-view) * [`post.view`](/developer-docs/analytics-sdk/events/post-view) * [`post.click`](/developer-docs/analytics-sdk/events/post-click) * [`post.view.popup`](/developer-docs/analytics-sdk/events/post-view-popup) * [`post.clap`](/developer-docs/analytics-sdk/events/post-clap) * [`product.click.tag`](/developer-docs/analytics-sdk/events/product-click-tag) * [`product.click.post`](/developer-docs/analytics-sdk/events/product-click-post) * [`product.click.card`](/developer-docs/analytics-sdk/events/product-click-card) * [`gallery.load_more`](/developer-docs/analytics-sdk/events/gallery-load-more) * [`gallery.upload_cta_click`](/developer-docs/analytics-sdk/events/gallery-upload-cta-click) Unknown event names are ignored. ## `trackSale(data)` Tracks a completed storefront purchase as `sale.complete`. Use this for manual storefront implementations. Standard Shopify sales tracking uses the checkout web pixel path instead of calling [`trackSale()`](/developer-docs/analytics-sdk/api#tracksaledata). ```ts theme={"system"} import { trackSale } from '@cevoid/analytics-sdk' trackSale({ orderId: 'order_123', marketId: 'market_123', customerId: 'cust_456', currency: 'USD', revenue: 129.99, skus: ['SKU-1', 'SKU-2'] }) ``` Required fields: * `orderId` * `currency` * `revenue` Optional fields: * `marketId` * `customerId` * `skus` Use [`trackSale()`](/developer-docs/analytics-sdk/api#tracksaledata) for completed purchases, not [`trackEvent()`](/developer-docs/analytics-sdk/api#trackeventname-data) with `sale.complete`. ## `identify(data)` Attaches profile-level context to future events. ```ts theme={"system"} import { identify } from '@cevoid/analytics-sdk' identify({ profileId: 'profile_123', externalId: 'shopify_customer_456' }) ``` Supported fields: * `profileId?: string` * `externalId?: string` This data is stored in SDK memory and attached to future tracked events. Call `identify()` again to replace the current identity payload. ## `reset()` Clears SDK initialization state, deferred events, and in-memory identity data. ```ts theme={"system"} import { reset } from '@cevoid/analytics-sdk' reset() ``` Use this on hard storefront context changes such as logout flows when you need to clear the current client-side analytics state. ## Related * [Installation](./installation) * [Event Types](./events/index) * [Manual Event Tracking](/developer-docs/analytics/track-events) * [Track Sales](/developer-docs/analytics/track-sales) # gallery.load_more Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/gallery-load-more Analytics SDK payload reference for the gallery.load_more event. Sent when a shopper loads more posts in a gallery widget. ```ts SDK input theme={"system"} trackEvent('gallery.load_more', { widgetId: 'gallery-homepage', widgetType: 'gallery', marketId: 'market_se', loadMoreType: 'button', pagePositionX: 0, pagePositionY: 1280 }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "marketId": "market_se", "loadMoreType": "button", "pagePositionX": 0, "pagePositionY": 1280 } ``` The browser event is emitted as `cevoid:gallery.load_more`. The forwarded payload is available on `event.detail`. ## Payload fields Gallery widget instance ID. Use the actual widget type, typically `gallery`. Market identifier for localized storefronts. How additional posts were loaded. Horizontal page position. Vertical page position. ## Related * [gallery.upload\_cta\_click](./gallery-upload-cta-click) * [SDK API](../api) # gallery.upload_cta_click Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/gallery-upload-cta-click Analytics SDK payload reference for the gallery.upload_cta_click event. Sent when a shopper clicks the upload CTA inside a gallery. ```ts SDK input theme={"system"} trackEvent('gallery.upload_cta_click', { widgetId: 'gallery-homepage', widgetType: 'gallery', marketId: 'market_se', pagePositionX: 0, pagePositionY: 920 }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "marketId": "market_se", "pagePositionX": 0, "pagePositionY": 920 } ``` The browser event is emitted as `cevoid:gallery.upload_cta_click`. The forwarded payload is available on `event.detail`. ## Payload fields Gallery widget instance ID. Use the actual widget type, typically `gallery`. Market identifier for localized storefronts. Horizontal page position. Vertical page position. ## Related * [gallery.load\_more](./gallery-load-more) * [SDK API](../api) # Event Types Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/index Browse Analytics SDK event names and open dedicated docs for each payload. Use this page when you want the Analytics SDK event catalog. Each event has its own page with trigger notes, an example payload, and field-level documentation. ## Widget lifecycle Sent when a widget finishes loading its initial content. Sent when a widget becomes visible to the shopper. ## Post events Sent when a post impression is tracked. Sent when a shopper clicks a post. Sent when a post is viewed in the popup experience. Sent when a shopper claps a post. ## Product click events Sent when a shopper clicks a tagged product from a post. Sent when a shopper clicks through to a product from a post. Sent when a shopper clicks through to a product from a card widget. ## Gallery actions Sent when a shopper loads more posts in a gallery. Sent when a shopper clicks the gallery upload CTA. ## Conversion event Sent by `trackSale()` when a completed purchase is tracked. ## Related * [SDK API](../api) * [Manual Event Tracking](../../analytics/track-events) * [Track Sales](../../analytics/track-sales) # post.clap Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/post-clap Analytics SDK payload reference for the post.clap event. Sent when a shopper claps a post. ```ts SDK input theme={"system"} trackEvent('post.clap', { widgetId: 'gallery-homepage', widgetType: 'gallery', postId: 'post_123', marketId: 'market_se', postPosition: 1, taggedProductIds: ['prod_1', 'prod_2'] }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "postId": "post_123", "marketId": "market_se", "postPosition": 1, "taggedProductIds": ["prod_1", "prod_2"] } ``` The browser event is emitted as `cevoid:post.clap`. The forwarded payload is available on `event.detail`. ## Payload fields Widget instance ID that showed the post. The rendered widget type. Cevoid post ID. Market identifier for localized storefronts. Position of the post in the widget. Product IDs associated with the post. ## Related * [post.view](./post-view) * [post.click](./post-click) # post.click Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/post-click Analytics SDK payload reference for the post.click event. Sent when a shopper clicks a post. ```ts SDK input theme={"system"} trackEvent('post.click', { widgetId: 'gallery-homepage', widgetType: 'gallery', postId: 'post_123', marketId: 'market_se', postPosition: 4, taggedProductIds: ['prod_1', 'prod_2'] }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "postId": "post_123", "marketId": "market_se", "postPosition": 4, "taggedProductIds": ["prod_1", "prod_2"] } ``` The browser event is emitted as `cevoid:post.click`. The forwarded payload is available on `event.detail`. ## Payload fields Widget instance ID that showed the post. The rendered widget type. Cevoid post ID. Market identifier for localized storefronts. Position of the post in the widget. Product IDs associated with the post. ## Related * [post.view](./post-view) * [product.click.post](./product-click-post) # post.view Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/post-view Analytics SDK payload reference for the post.view event. Sent when a post impression is tracked. ```ts SDK input theme={"system"} trackEvent('post.view', { widgetId: 'gallery-homepage', widgetType: 'gallery', postId: 'post_123', marketId: 'market_se', postPosition: 1, taggedProductIds: ['prod_1', 'prod_2'] }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "postId": "post_123", "marketId": "market_se", "postPosition": 1, "taggedProductIds": ["prod_1", "prod_2"] } ``` The browser event is emitted as `cevoid:post.view`. The forwarded payload is available on `event.detail`. ## Payload fields Widget instance ID that showed the post. The rendered widget type. Cevoid post ID. Market identifier for localized storefronts. Position of the post in the widget. Product IDs associated with the post. ## Related * [post.click](./post-click) * [post.view.popup](./post-view-popup) * [post.clap](./post-clap) # post.view.popup Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/post-view-popup Analytics SDK payload reference for the post.view.popup event. Sent when a post is viewed in the popup experience. ```ts SDK input theme={"system"} trackEvent('post.view.popup', { widgetId: 'gallery-homepage', widgetType: 'gallery', postId: 'post_123', marketId: 'market_se', postPosition: 1, taggedProductIds: ['prod_1', 'prod_2'] }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "postId": "post_123", "marketId": "market_se", "postPosition": 1, "taggedProductIds": ["prod_1", "prod_2"] } ``` The browser event is emitted as `cevoid:post.view.popup`. The forwarded payload is available on `event.detail`. ## Payload fields Widget instance ID that showed the post. The rendered widget type. Cevoid post ID. Market identifier for localized storefronts. Position of the post in the widget. Product IDs associated with the post. ## Related * [post.view](./post-view) * [post.click](./post-click) # product.click.card Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/product-click-card Analytics SDK payload reference for the product.click.card event. Sent when a shopper clicks through to a product from a card widget. ```ts SDK input theme={"system"} trackEvent('product.click.card', { widgetId: 'card-homepage', widgetType: 'card', postId: 'post_123', productId: 'prod_1', marketId: 'market_se' }) ``` ```json Browser event detail theme={"system"} { "widgetId": "card-homepage", "widgetType": "card", "postId": "post_123", "productId": "prod_1", "marketId": "market_se" } ``` The browser event is emitted as `cevoid:product.click.card`. The forwarded payload is available on `event.detail`. ## Payload fields Widget instance ID that showed the product. The rendered widget type. Cevoid post ID tied to the product click. Product ID that was clicked. Market identifier for localized storefronts. ## Related * [product.click.tag](./product-click-tag) * [product.click.post](./product-click-post) # product.click.post Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/product-click-post Analytics SDK payload reference for the product.click.post event. Sent when a shopper clicks through to a product from a post. ```ts SDK input theme={"system"} trackEvent('product.click.post', { widgetId: 'gallery-homepage', widgetType: 'gallery', postId: 'post_123', productId: 'prod_1', marketId: 'market_se' }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "postId": "post_123", "productId": "prod_1", "marketId": "market_se" } ``` The browser event is emitted as `cevoid:product.click.post`. The forwarded payload is available on `event.detail`. ## Payload fields Widget instance ID that showed the product. The rendered widget type. Cevoid post ID tied to the product click. Product ID that was clicked. Market identifier for localized storefronts. ## Related * [product.click.tag](./product-click-tag) * [product.click.card](./product-click-card) # product.click.tag Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/product-click-tag Analytics SDK payload reference for the product.click.tag event. Sent when a shopper clicks a tagged product from a post. ```ts SDK input theme={"system"} trackEvent('product.click.tag', { widgetId: 'gallery-homepage', widgetType: 'gallery', postId: 'post_123', productId: 'prod_1', marketId: 'market_se' }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "postId": "post_123", "productId": "prod_1", "marketId": "market_se" } ``` The browser event is emitted as `cevoid:product.click.tag`. The forwarded payload is available on `event.detail`. ## Payload fields Widget instance ID that showed the product. The rendered widget type. Cevoid post ID tied to the product click. Product ID that was clicked. Market identifier for localized storefronts. ## Related * [product.click.post](./product-click-post) * [product.click.card](./product-click-card) # sale.complete Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/sale-complete Analytics SDK payload reference for the sale.complete conversion event. Sent by `trackSale()` when a completed purchase is tracked. The SDK emits the browser event `cevoid:sale.complete` and sends the internal event `sale.complete`. ```ts SDK input theme={"system"} trackSale({ orderId: 'order_123', marketId: 'market_123', customerId: 'cust_456', currency: 'USD', revenue: 129.99, skus: ['SKU-1', 'SKU-2'] }) ``` ```json Browser event detail theme={"system"} { "orderId": "order_123", "marketId": "market_123", "customerId": "cust_456", "currency": "USD", "revenue": 129.99, "skus": ["SKU-1", "SKU-2"] } ``` The browser event is emitted as `cevoid:sale.complete`. The forwarded payload is available on `event.detail`. ## Payload fields Order identifier. Market identifier used for SKU resolution in telemetry. Customer identifier. ISO currency code. Decimal major-unit amount in `currency`. **Example:** `129.99` Purchased SKUs used for telemetry-side product resolution. ## Notes * Provide `revenue` in the same currency as `currency`, for example `129.99` with `USD`. * Use `trackSale(data)` for conversions rather than `trackEvent('sale.complete', ...)`. ## Related * [Track Sales](/developer-docs/analytics/track-sales) * [SDK API](../api) # widget.load Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/widget-load Analytics SDK payload reference for the widget.load event. Sent when a widget finishes loading its initial content. ```ts SDK input theme={"system"} trackEvent('widget.load', { widgetId: 'gallery-homepage', widgetType: 'gallery', marketId: 'market_se', postsLoadedCount: 12, fallbackPostsCount: 0, pagePositionX: 0, pagePositionY: 640 }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "marketId": "market_se", "postsLoadedCount": 12, "fallbackPostsCount": 0, "pagePositionX": 0, "pagePositionY": 640 } ``` The browser event is emitted as `cevoid:widget.load`. The forwarded payload is available on `event.detail`. ## Payload fields Your Cevoid widget instance ID. The rendered widget type. Market identifier for localized storefronts. Number of posts loaded into the widget. Number of fallback posts used. Horizontal page position. Vertical page position. ## Related * [widget.view](./widget-view) * [SDK API](../api) # widget.view Source: https://docs.cevoid.com/developer-docs/analytics-sdk/events/widget-view Analytics SDK payload reference for the widget.view event. Sent when a widget becomes visible to the shopper. ```ts SDK input theme={"system"} trackEvent('widget.view', { widgetId: 'gallery-homepage', widgetType: 'gallery', marketId: 'market_se', postsLoadedCount: 12, fallbackPostsCount: 0, pagePositionX: 0, pagePositionY: 640 }) ``` ```json Browser event detail theme={"system"} { "widgetId": "gallery-homepage", "widgetType": "gallery", "marketId": "market_se", "postsLoadedCount": 12, "fallbackPostsCount": 0, "pagePositionX": 0, "pagePositionY": 640 } ``` The browser event is emitted as `cevoid:widget.view`. The forwarded payload is available on `event.detail`. ## Payload fields Your Cevoid widget instance ID. The rendered widget type. Market identifier for localized storefronts. Number of posts loaded into the widget. Number of fallback posts used. Horizontal page position. Vertical page position. ## Related * [widget.load](./widget-load) * [SDK API](../api) # Installation Source: https://docs.cevoid.com/developer-docs/analytics-sdk/installation Install and initialize the Cevoid Analytics SDK with a script tag, npm, or React. Use this page when you already know you need the Cevoid Analytics SDK and want the supported installation paths. If you are still deciding between automatic gallery behavior, browser-event subscriptions, or manual tracking, start with [Overview](../analytics). ## Choose one path Use the installation path that matches how your storefront is built: * **Script tag**: fastest setup when you want browser-only initialization and no package imports * **npm package**: best default when you control storefront application code directly * **React**: use when your storefront already renders through React ## Script tag Use the script tag when you want the fastest setup and do not need package imports. ```html theme={"system"} ``` The script reads these `data-*` attributes: * `data-publishable-key` * `data-enable-session-tracking` * `data-cookie-domain` * `data-api-host` * `data-emit-browser-events` After loading, the script auto-initializes and exposes: * `window.cevoid.init` * `window.cevoid.reset` * `window.cevoid.identify` * `window.cevoid.trackEvent` * `window.cevoid.trackSale` Verification: * open the page after the script loads * confirm `window.cevoid` exists * send one test call such as `window.cevoid.trackSale(...)` or listen for a gallery browser event ## npm package Use the package entry point when you want full control over initialization from your storefront code. ```bash theme={"system"} npm install @cevoid/analytics-sdk ``` ```ts theme={"system"} import { init, trackEvent } from '@cevoid/analytics-sdk' init({ publishableKey: 'cev_pk_...', enableSessionTracking: true, cookieDomain: '.example.com' }) trackEvent('widget.load', { widgetId: 'gallery-homepage', widgetType: 'gallery', postsLoadedCount: 12 }) ``` Verification: * confirm your app starts without SDK import errors * trigger one supported tracking call * if `emitBrowserEvents` is left on, confirm the matching browser event appears on `window` ## React Use the React entry point when your storefront already renders through React. ```bash theme={"system"} npm install @cevoid/analytics-sdk ``` ```tsx theme={"system"} import { Analytics as CevoidAnalytics, trackEvent } from '@cevoid/analytics-sdk/react' export function App() { return ( <> ) } ``` Verification: * mount the `Analytics` component once near your app root * trigger one supported tracking call from React code * confirm the event path works before layering in session tracking or consent handling ## Configuration Call `init()` once before sending events. The React component uses the same props. | Option | Type | Default | Description | | ----------------------- | --------- | ------------------------------ | ------------------------------------------------------------------------ | | `publishableKey` | `string` | — | Required workspace publishable key. | | `enableSessionTracking` | `boolean` | `false` | Enables Cevoid session tracking after consent checks pass. | | `cookieDomain` | `string` | — | Sets the domain on the `ca_session` cookie. | | `emitBrowserEvents` | `boolean` | `true` | Emits browser `CustomEvent`s such as `cevoid:post.click` on `window`. | | `apiHost` | `string` | `https://telemetry.cevoid.com` | Overrides the telemetry host for development or controlled environments. | Repeated `init()` calls after the first successful initialization are ignored. ## Related * [SDK API](./api) * [Event Types](./events/index) * [Session Tracking](../analytics/setup-session-tracking) * [Consent](../analytics/consent) # Consent Source: https://docs.cevoid.com/developer-docs/analytics/consent Understand when the Cevoid Analytics SDK creates a session, when it does not, and how consent affects session IDs. Use this page when you need the exact rules for Cevoid session creation and `session_id` attachment. If you only want the operational setup steps, use [Session Tracking](./setup-session-tracking) instead. ## Short answer The SDK only attempts to create a Cevoid session when both of these are true: 1. `enableSessionTracking` is enabled 2. The consent checks resolve to granted If consent is denied, events can still be sent, but `session_id` is omitted. On a non-Shopify site with no GTM consent entry and no `window.cevoidTrackingConsent` value, the consent checks default to granted. ## Session cookie name The current Cevoid session cookie name is `ca_session`. `cevoid_sid` is the legacy cookie name. The SDK will migrate an existing legacy cookie into `ca_session` and clean up the old cookie when possible. If your storefront requires cookie disclosures before analytics storage is enabled, document `ca_session` in your cookie policy before you turn on session tracking in production. ## Consent sources When session tracking is enabled, the SDK checks up to three sources: If none of these sources are present on a non-Shopify site, the overall consent result defaults to granted. ### Shopify Customer Privacy API If Shopify is not present, this check defaults to granted. If Shopify is present, the SDK tries to load the `consent-tracking-api` feature and waits up to 5 seconds: * if the feature loads, it uses `window.Shopify.customerPrivacy.userCanBeTracked()` * if feature loading fails or times out, the Shopify check resolves to denied ### GTM `dataLayer` If `window.dataLayer` is missing or is not an array, this check defaults to granted. If a consent entry is present, the SDK reads `analytics_storage` from the first `['consent', ..., {...}]` style entry: * `analytics_storage === 'granted'` means granted * any other value means denied ### `window.cevoidTrackingConsent` If this global is missing, this check defaults to granted. If it is present: * `'granted'` means granted * any other value means denied ## What happens when consent is granted If consent resolves to granted, the SDK: * creates or refreshes `ca_session` * uses a 30-minute rolling expiry * attaches `session_id` to tracked events Cookie attributes: * Name: `ca_session` * Path: `/` * SameSite: `Lax` * Domain: only set when you pass `cookieDomain` ## What happens when consent is denied If consent resolves to denied: * the SDK clears the Cevoid session state * the SDK does not create `ca_session` * tracked events can still be sent * those events do not include `session_id` ## What happens when cookies cannot be written If consent is granted but the browser blocks cookie writes, the SDK falls back to an in-memory session for the current page runtime. That fallback: * does not persist across full page reloads * still allows a session value to be attached during the current runtime This fallback does **not** apply to denied consent. ## What happens while consent is resolving When `enableSessionTracking` is enabled, tracked events are deferred until consent resolution finishes. After consent resolves: * if granted, the SDK creates or refreshes the session and then sends the deferred events * if denied, the SDK sends the deferred events without `session_id` ## Practical examples ### Gallery on a non-Shopify site with no custom consent signals Result: * consent defaults to granted * `ca_session` is created if session tracking is enabled ### Shopify storefront where tracking is denied Result: * no `ca_session` is created * events can still be sent without `session_id` ### Site where cookies are blocked Result: * no persistent `ca_session` * in-memory session fallback for the current runtime only ## Related * [Session Tracking](./setup-session-tracking) * [Installation](../analytics-sdk/installation) # Forward Browser Events to Google Analytics Source: https://docs.cevoid.com/developer-docs/analytics/forward-events-to-ga Listen to Cevoid browser events and forward them into GA4 or GTM without duplicating gallery tracking calls. Use this page when you already use Cevoid galleries or cards and want their emitted browser events in GA4 or GTM. If you need to manually send Cevoid widget events from custom code, use [Manual Event Tracking](./track-events) instead. ## Default gallery behavior Cevoid galleries and cards use the UGC tracking surface internally and emit browser [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)s by default. That means you usually do **not** need to call [`trackEvent()`](../analytics-sdk/api#trackeventname-data) yourself just to forward gallery interactions to GA. The browser event name format is: ```text theme={"system"} cevoid: ``` Examples: * `cevoid:widget.load` * `cevoid:post.click` * `cevoid:product.click.tag` * `cevoid:gallery.load_more` * `cevoid:sale.complete` The forwarded payload is available on [`event.detail`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail). ```js theme={"system"} window.addEventListener('cevoid:post.click', (event) => { console.log(event.detail) }) ``` ## Consent note Browser events are emitted when the SDK tracking call runs unless `emitBrowserEvents` is disabled. Consent affects whether tracked events get a Cevoid `session_id`. It does not prevent the browser [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) itself from being emitted. ## Option 1: Forward directly with `gtag` Use this when GA4 is installed directly with `gtag()`. ```html theme={"system"} ``` ## Option 2: Forward through GTM Use this when your site already routes analytics through Google Tag Manager. ```html theme={"system"} ``` Then in GTM: 1. Create a Custom Event trigger for `cevoid_post_click` 2. Create a GA4 Event tag 3. Map the pushed fields to GA4 parameters ## Recommended events to forward Start with the lower-volume action events that are easiest to report on: * [`post.click`](../analytics-sdk/events/post-click) * [`product.click.tag`](../analytics-sdk/events/product-click-tag) * [`product.click.post`](../analytics-sdk/events/product-click-post) * [`product.click.card`](../analytics-sdk/events/product-click-card) * [`gallery.load_more`](../analytics-sdk/events/gallery-load-more) * [`gallery.upload_cta_click`](../analytics-sdk/events/gallery-upload-cta-click) * [`sale.complete`](../analytics-sdk/events/sale-complete) Forward impression-style events like [`widget.view`](../analytics-sdk/events/widget-view) or [`post.view`](../analytics-sdk/events/post-view) only if you want that extra volume in GA. ## Example: forward multiple events ```html theme={"system"} ``` ## Example: only forward one gallery ```html theme={"system"} ``` ## Related * [Using Cevoid Galleries](./using-cevoid-galleries) * [SDK API](../analytics-sdk/api) * [Event Types](../analytics-sdk/events/index) # Overview Source: https://docs.cevoid.com/developer-docs/analytics/index Choose the right Cevoid analytics integration path for your storefront. Use this page first when you are deciding how to implement Cevoid analytics on a storefront. If you already know the exact SDK method or event payload you need, skip to [Installation](../analytics-sdk/installation), [SDK API](../analytics-sdk/api), or [Event Types](../analytics-sdk/events/index). ## Choose your path Gallery and card widgets already initialize Cevoid UGC tracking and emit browser events automatically. Listen to Cevoid browser events on `window` and forward them into your existing analytics setup. Use [`trackEvent()`](../analytics-sdk/api#trackeventname-data) when you render Cevoid interactions yourself and need to send widget-style events manually. Shopify uses the checkout web pixel path. Non-Shopify storefronts use the manual sales-tracking path. Add Cevoid session IDs to events when consent allows it. See when `ca_session` is created, when it is not, and how denied consent affects events. ## Quick answers ### I embedded a Cevoid gallery or card. Do I need to call [`trackEvent()`](../analytics-sdk/api#trackeventname-data)? Usually no. Cevoid galleries and cards initialize the UGC SDK internally and send the core widget, post, product, and gallery events automatically. ### I want those gallery events in GA4 or GTM. Use [Forward Browser Events to GA](./forward-events-to-ga). The SDK emits browser [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)s like `cevoid:post.click` by default, so you usually listen for them instead of duplicating the tracking calls. ### I am rendering Cevoid interactions in my own storefront code. Use [Manual Event Tracking](./track-events) and send the supported Cevoid event names yourself. ### I want to track completed purchases. Use [Track Sales](./track-sales). Shopify storefronts use the checkout web pixel path only; non-Shopify storefronts use the manual `trackSale()` path. ### I need Cevoid session IDs on events. Use [Session Tracking](./setup-session-tracking) and [Consent](./consent). Session tracking is optional and only attaches `session_id` when consent resolves to granted. ## Related * [Using Cevoid Galleries](./using-cevoid-galleries) * [Forward Browser Events to GA](./forward-events-to-ga) * [Manual Event Tracking](./track-events) * [Track Sales](./track-sales) * [Session Tracking](./setup-session-tracking) * [Consent](./consent) # Session Tracking Source: https://docs.cevoid.com/developer-docs/analytics/setup-session-tracking Enable Cevoid session tracking and verify when session IDs are attached to analytics events. Use this page when you want Cevoid to attach session IDs to tracked events. If you only need the exact consent and cookie rules, use [Consent](./consent) instead. Session tracking is optional. Without it, the SDK still sends events, but those events do not include a Cevoid `session_id`. ## Why this matters Session tracking is what allows Cevoid to connect supported gallery activity and completed orders. That means: * when you enable session tracking together with sales tracking, Cevoid can measure attribution between Cevoid widget interactions and a completed order when consent resolves to granted * when you enable session tracking without sales tracking, Cevoid can still measure gallery and card behavior, but there is no completed order to connect those interactions to * when you enable sales tracking without session tracking, the sale can still be recorded, but Cevoid usually cannot connect a Cevoid widget event to that order In practice, session tracking is usually most valuable when it is enabled together with sales tracking. ## What session tracking adds When session tracking is enabled and consent resolves to granted, the SDK: * creates or refreshes `ca_session` * uses a 30-minute rolling session lifetime * attaches `session_id` to tracked events If consent is denied: * events can still be sent * `session_id` is omitted ## 1. Turn on session tracking Enable it in `init()` or in the React component props. ```ts theme={"system"} import { init } from '@cevoid/analytics-sdk' init({ publishableKey: 'cev_pk_...', enableSessionTracking: true }) ``` React example: ```tsx theme={"system"} import { Analytics as CevoidAnalytics } from '@cevoid/analytics-sdk/react' export function App() { return } ``` ## 2. Configure `cookieDomain` when needed If your storefront spans subdomains, set `cookieDomain` so `ca_session` is written where you need it. ```ts theme={"system"} init({ publishableKey: 'cev_pk_...', enableSessionTracking: true, cookieDomain: '.example.com' }) ``` Use `cookieDomain` when: * your storefront runs on multiple subdomains * you want the session cookie shared across those subdomains ## 3. Add the cookie-policy entry when needed If your storefront requires cookie disclosures before enabling analytics storage, add `ca_session` to your cookie policy before enabling session tracking in production. Suggested description: `Collects statistics from the visitor's interaction with Cevoid galleries on the website, such as post views, gallery views, post clicks, product clicks and statistics about order value after checkout.` ## 4. Make sure consent is available When session tracking is enabled, the SDK checks these consent sources when they are present: * Shopify Customer Privacy API * `dataLayer` consent entries for `analytics_storage` * `window.cevoidTrackingConsent` On a non-Shopify site with no `dataLayer` consent entry and no `window.cevoidTrackingConsent` value, consent defaults to granted and the SDK can create `ca_session`. If any present consent source resolves to denied, the SDK still sends events without a Cevoid session ID. ## 5. Verify the session flow After initialization: * look for `ca_session` in the browser * trigger one or more tracked events * if you use Shopify, GTM consent, or `window.cevoidTrackingConsent`, confirm that your consent source is available before expecting `session_id` If consent is granted but cookies cannot be written, the SDK falls back to an in-memory session for the current page runtime only. ## Common mistakes * expecting a session ID without enabling `enableSessionTracking` * forgetting `cookieDomain` when the storefront spans subdomains * assuming missing `session_id` means the event was dropped * on Shopify, testing before the relevant consent source is available ## Related * [Consent](./consent) * [Installation](../analytics-sdk/installation) * [Using Cevoid Galleries](./using-cevoid-galleries) # Manual Event Tracking Source: https://docs.cevoid.com/developer-docs/analytics/track-events Use trackEvent() when you need to send Cevoid widget interaction events manually from custom storefront code. Use this page when you need to call [`trackEvent()`](../analytics-sdk/api#trackeventname-data) yourself from custom storefront code. If you are using standard Cevoid galleries or cards, do not start here. Those widget surfaces already emit the core Cevoid UGC events automatically. For payload-by-payload reference, use [SDK API](../analytics-sdk/api) and [Event Types](../analytics-sdk/events/index). ## When to use [`trackEvent()`](../analytics-sdk/api#trackeventname-data) Use [`trackEvent()`](../analytics-sdk/api#trackeventname-data) when: * you render Cevoid interactions in your own storefront UI * you need to manually mirror Cevoid widget-style actions from custom code * you want those custom interactions to follow the supported Cevoid event names Do not use [`trackEvent()`](../analytics-sdk/api#trackeventname-data) just to forward standard gallery or card events into GA or GTM. In that case, use [Forward Browser Events to GA](./forward-events-to-ga). ## 1. Initialize the SDK Initialize the SDK once before the first tracking call. ```ts theme={"system"} import { init } from '@cevoid/analytics-sdk' init({ publishableKey: 'cev_pk_...' }) ``` React example: ```tsx theme={"system"} import { Analytics as CevoidAnalytics } from '@cevoid/analytics-sdk/react' export function App() { return } ``` Verification: * trigger one manual call in the browser * confirm your handler runs without an initialization error * if browser events are enabled, confirm a matching `cevoid:` [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) fires on `window` ## 2. Send supported event names Send the exact dotted Cevoid event name that matches the UI action. ```ts theme={"system"} import { trackEvent } from '@cevoid/analytics-sdk' trackEvent('widget.load', { widgetId: 'gallery-homepage', widgetType: 'gallery', postsLoadedCount: 12 }) trackEvent('post.click', { widgetId: 'gallery-homepage', widgetType: 'gallery', postId: 'post_123', postPosition: 1 }) ``` Common manual event groups: * widget lifecycle: [`widget.load`](../analytics-sdk/events/widget-load), [`widget.view`](../analytics-sdk/events/widget-view) * post interactions: [`post.view`](../analytics-sdk/events/post-view), [`post.click`](../analytics-sdk/events/post-click), [`post.view.popup`](../analytics-sdk/events/post-view-popup), [`post.clap`](../analytics-sdk/events/post-clap) * product interactions: [`product.click.tag`](../analytics-sdk/events/product-click-tag), [`product.click.post`](../analytics-sdk/events/product-click-post), [`product.click.card`](../analytics-sdk/events/product-click-card) * gallery actions: [`gallery.load_more`](../analytics-sdk/events/gallery-load-more), [`gallery.upload_cta_click`](../analytics-sdk/events/gallery-upload-cta-click) ## 3. Use real Cevoid IDs Pass the real Cevoid identifiers from the rendered experience: * `widgetId` * `postId` * `productId` * `marketId` when relevant Do not substitute labels, DOM IDs, or storefront-only identifiers unless they are the actual Cevoid IDs used by your integration. ## 4. Keep payload details in the reference pages Use the reference pages for accepted values and field requirements: * [SDK API](../analytics-sdk/api) * [Event Types](../analytics-sdk/events/index) ## Common mistakes * calling [`trackEvent()`](../analytics-sdk/api#trackeventname-data) before `init()` * using manual tracking for standard Cevoid galleries or cards when the events are already emitted automatically * using the wrong event name for the actual UI surface * omitting required Cevoid IDs ## Related * [Using Cevoid Galleries](./using-cevoid-galleries) * [Forward Browser Events to GA](./forward-events-to-ga) * [SDK API](../analytics-sdk/api) * [Event Types](../analytics-sdk/events/index) # Track Sales Source: https://docs.cevoid.com/developer-docs/analytics/track-sales Track completed storefront purchases in Cevoid with the right setup for Shopify or non-Shopify storefronts. Use this page when you want Cevoid to receive completed purchase events from your storefront. If you are trying to instrument widget, post, or product interactions, use [Using Cevoid Galleries](./using-cevoid-galleries) or [Manual Event Tracking](./track-events) instead. For the exact manual SDK method surface and payload reference, use [SDK API](../analytics-sdk/api) and [sale.complete](../analytics-sdk/events/sale-complete). ## Choose the right sales-tracking path ### Shopify storefronts If your storefront runs on Shopify, Cevoid sales tracking is handled through the Shopify checkout web pixel. That means: * you do not need `@cevoid/analytics-sdk` just to track completed sales * you do not need to call `trackSale()` for the standard Shopify setup * you should enable the Cevoid checkout web pixel for each Shopify store that should send checkout events Use the dashboard setup flow for this path. Do not combine the Shopify web-pixel path with manual `trackSale()` calls for the same storefront. If you run on Shopify, follow the Shopify sales-tracking setup only. ### Non-Shopify storefronts If your storefront is not Shopify, use the manual sales-tracking path. That means: * initialize Cevoid tracking in your storefront * call `trackSale()` when an order is completed * send one completed sale per final order Use this path only when your storefront is not Shopify. ## When to use `trackSale()` Use `trackSale()` when both of these are true: * your storefront is not Shopify * you have a final completed order record to send to Cevoid Typical trigger points: * order confirmation pages * checkout success callbacks * server-confirmed storefront completion handlers Do not call `trackSale()` before the order is actually completed. For Shopify storefronts, the supported sales-tracking path is the checkout web pixel. Do not add manual `trackSale()` calls on top of it. ## Why session tracking usually belongs with sales tracking Cevoid uses the session layer to measure attribution between Cevoid gallery activity and a completed order. That means: * if session tracking is enabled and consent resolves to granted, Cevoid can connect supported gallery interactions and the completed sale through `session_id` * if session tracking is not enabled, the sale can still be recorded, but Cevoid usually cannot connect a Cevoid widget event to that order In practice, you usually want session tracking enabled when you enable sales tracking. ## 1. Initialize the SDK ```ts theme={"system"} import { init } from '@cevoid/analytics-sdk' init({ publishableKey: 'cev_pk_...' }) ``` ## 2. Optionally identify the shopper If you already know the shopper identity, call `identify()` first so the conversion event can include that context. ```ts theme={"system"} import { identify } from '@cevoid/analytics-sdk' identify({ profileId: 'profile_123', externalId: 'shopify_customer_456' }) ``` ## 3. Send the completed sale ```ts theme={"system"} import { trackSale } from '@cevoid/analytics-sdk' trackSale({ orderId: 'order_123', marketId: 'market_123', customerId: 'cust_456', currency: 'USD', revenue: 129.99, skus: ['SKU-1', 'SKU-2'] }) ``` Required fields: * `orderId` * `currency` * `revenue` Optional fields: * `marketId` * `customerId` * `skus` `revenue` must be sent as a decimal major-unit amount in the same currency as `currency`, such as `129.99 USD`. ## 4. Send one event per completed order Recommended pattern: * choose one stable completion trigger * send one conversion event per completed order * prevent duplicates on page reload or repeated callbacks Cevoid also deduplicates completed sales server-side by workspace and `orderId`, so repeated `trackSale()` calls for the same order do not create multiple counted sales. You should still do your own best-effort deduplication and avoid sending the same order more than once from the client or server. Avoid sending `trackSale()` from: * cart pages * checkout start events * optimistic client-side states before payment confirmation ## 5. Verify the sales flow After setup: * complete one real or test order through the path you implemented * confirm the order only triggers one completed sale event from your chosen integration path * if session tracking is enabled and consent resolves to granted, confirm the sale can include `session_id` If you are on Shopify, verify the checkout web pixel path. If you are not on Shopify, verify your manual `trackSale()` trigger. ## Session note Session tracking is optional, but it is usually recommended when you want sales attribution. If session tracking is enabled and consent resolves to granted, `trackSale()` can include a Cevoid `session_id`. If consent is denied: * the conversion event can still be sent * `session_id` is omitted If you enable session tracking without sales tracking, Cevoid can still measure how users interact with galleries and cards. That setup is valid when you only need widget analytics and do not need to connect those interactions to completed orders. ## Related * [Overview](./index) * [SDK API](../analytics-sdk/api) * [sale.complete](../analytics-sdk/events/sale-complete) * [Session Tracking](./setup-session-tracking) * [Consent](./consent) # Using Cevoid Galleries Source: https://docs.cevoid.com/developer-docs/analytics/using-cevoid-galleries Understand what Cevoid galleries and cards track automatically and when you still need custom analytics work. Use this page when you embed Cevoid galleries or cards on a storefront and want to understand what happens automatically. If you are not using Cevoid widget surfaces, skip this page and go to [Manual Event Tracking](./track-events) or [Track Sales](./track-sales). ## What happens automatically Cevoid galleries and cards already initialize the UGC tracking surface internally when a workspace publishable key is available. That means the widget can automatically send the core Cevoid on-site events, including: * `widget.load` * `widget.view` * `post.view` * `post.click` * `post.view.popup` * `post.clap` * `product.click.tag` * `product.click.post` * `product.click.card` * `gallery.load_more` * `gallery.upload_cta_click` The widgets also emit the matching browser events by default, such as: * `cevoid:post.click` * `cevoid:product.click.tag` * `cevoid:gallery.load_more` The browser event payload is available on [`event.detail`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail). ## Default gallery path If you use a standard Cevoid gallery or card, the normal setup is: * Cevoid sends the gallery and card events automatically * Cevoid emits the matching browser [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)s automatically * if you want GA4 or GTM forwarding, you listen to those browser events on `window` In that setup, you do **not** call [`trackEvent()`](../analytics-sdk/api#trackeventname-data) yourself just because you embedded a gallery or card. ## When you need a different path Leave the default gallery path when one of these is true: * you render Cevoid interactions in custom storefront code outside the standard widgets * you want completed purchase tracking on a non-Shopify storefront * you need Cevoid session IDs on events and want to verify consent behavior In those cases: * use [Manual Event Tracking](./track-events) for custom Cevoid interaction tracking * use [Track Sales](./track-sales) for non-Shopify completed purchases * use [Session Tracking](./setup-session-tracking) and [Consent](./consent) for session behavior ## Recommended next step * Want GA or GTM forwarding: [Forward Browser Events to GA](./forward-events-to-ga) * Want exact session behavior: [Session Tracking](./setup-session-tracking) * Want cookie and consent rules: [Consent](./consent) * Want payload details: [Event Types](../analytics-sdk/events/index) ## Related * [Forward Browser Events to GA](./forward-events-to-ga) * [Session Tracking](./setup-session-tracking) * [Consent](./consent) * [Event Types](../analytics-sdk/events/index) # Docs Index Source: https://docs.cevoid.com/developer-docs/docs-index Browse the Cevoid developer docs by purpose, product surface, and reference type. Use this page when you want a single discoverability index for the developer docs. It is useful for browsing, search, and tooling, but it is not the main onboarding path for new developers. ## Start here * [Developer Docs Overview](./index): platform-level entry page * [UGC Widgets Overview](./ugc-widgets): use this first when embedding Cevoid UGC galleries or cards * [Analytics Overview](./analytics): use this first for storefront Analytics implementation paths ## UGC widget guides * [Embed Galleries and Cards](./ugc-widgets/embed) * [Dynamic Galleries](./ugc-widgets/dynamic-galleries) * [Runtime Helpers](./ugc-widgets/runtime-helpers) * [Advanced](./ugc-widgets/advanced) * [Programmatic Market Values](./ugc-widgets/market-values) * [CMS Blocks](./ugc-widgets/cms-blocks) ## Analytics implementation guides * [Using Cevoid Galleries](./analytics/using-cevoid-galleries) * [Forward Browser Events to GA](./analytics/forward-events-to-ga) * [Manual Event Tracking](./analytics/track-events) * [Track Sales](./analytics/track-sales) * [Session Tracking](./analytics/setup-session-tracking) * [Consent](./analytics/consent) ## Analytics SDK reference * [Installation](./analytics-sdk/installation) * [SDK API](./analytics-sdk/api) * [Event Types Index](./analytics-sdk/events) * [widget.load](./analytics-sdk/events/widget-load) * [widget.view](./analytics-sdk/events/widget-view) * [post.view](./analytics-sdk/events/post-view) * [post.click](./analytics-sdk/events/post-click) * [post.view.popup](./analytics-sdk/events/post-view-popup) * [post.clap](./analytics-sdk/events/post-clap) * [product.click.tag](./analytics-sdk/events/product-click-tag) * [product.click.post](./analytics-sdk/events/product-click-post) * [product.click.card](./analytics-sdk/events/product-click-card) * [gallery.load\_more](./analytics-sdk/events/gallery-load-more) * [gallery.upload\_cta\_click](./analytics-sdk/events/gallery-upload-cta-click) * [sale.complete](./analytics-sdk/events/sale-complete) ## Other developer surfaces * [MCP](./mcp) * [Image Optimization](./images) * [Widget performance](./other/widget-performance) * [Custom CSS](./other/custom-css) * [API Reference](/api-reference) ## Product docs * [Help Center](/help-center) # Image Optimization Source: https://docs.cevoid.com/developer-docs/images Optimize Cevoid CDN image URLs for responsive storefronts and different display densities. Use this page when you fetch Cevoid image URLs and want to render them efficiently in a storefront. If you are looking for gallery or card implementation behavior, use [Analytics Overview](./analytics) or the [API Reference](/api-reference) instead. ## When to use this Use image optimization when: * you fetch raw Cevoid image URLs from the API * you render those images in a custom storefront UI * you want smaller responsive images instead of the original full-size asset Cevoid image URLs return the original image by default. Add the `class` query parameter when you want a pre-optimized size from the CDN. ## Quickstart 1. Fetch or receive the original Cevoid image URL. 2. Add `?class=` to request an optimized width. 3. Use the optimized URL in your storefront markup. 4. Add `srcset` only when you need responsive behavior across breakpoints. Example: ```html theme={"system"} User generated content ``` ## Available Image Classes The Cevoid CDN provides several pre-optimized image sizes: | Class | Width (pixels) | Use Case | | ---------- | --------------- | ----------------------------------- | | `original` | Full resolution | High-quality displays, print | | `1080` | 1080px | Desktop hero images, large displays | | `750` | 750px | Tablet landscape, desktop cards | | `640` | 640px | Tablet portrait, large mobile | | `480` | 480px | Mobile landscape | | `400` | 400px | Mobile portrait, thumbnails | | `320` | 320px | Small mobile screens | | `240` | 240px | Thumbnail grids | | `160` | 160px | Small thumbnails, avatars | ## Example: transform an API image URL When you fetch posts from the API, you'll receive image URLs like this: ```json theme={"system"} { "id": "WAz8eIbvDR60rouK", "images": [ { "url": "https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT", "width": 1920, "height": 1080 } ] } ``` Transform the URL by adding the `class` parameter: ```javascript theme={"system"} const originalUrl = 'https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT' const optimizedUrl = `${originalUrl}?class=640` console.log(optimizedUrl) ``` Result: ```text theme={"system"} https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640 ``` ## Performance guidance ### Choose the Right Size Select the image class that best matches your display requirements. Using unnecessarily large images wastes bandwidth and slows loading times. ### Responsive Images Use different image classes for different screen sizes: ```html theme={"system"} User generated content ``` ### Pick the nearest useful class ```javascript theme={"system"} function getOptimizedImageUrl(originalUrl, targetWidth) { const imageClasses = [160, 240, 320, 400, 480, 640, 750, 1080] const bestClass = imageClasses.find((size) => size >= targetWidth) || 'original' return `${originalUrl}?class=${bestClass}` } const imageUrl = 'https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT' const optimized = getOptimizedImageUrl(imageUrl, 400) ``` ## Best Practices ### 1. Match Image Size to Container Always choose an image class that matches or slightly exceeds your container's display size: ```css theme={"system"} .image-container { width: 300px; } ``` ### 2. Consider Display Density For high-density displays (Retina, etc.), use an image class that's 2x your container size: ```js theme={"system"} const containerWidth = 200; const pixelRatio = window.devicePixelRatio || 1; const targetWidth = containerWidth * pixelRatio; const optimizedUrl = getOptimizedImageUrl(originalUrl, targetWidth); ``` ### 3. Lazy Loading Combine image optimization with lazy loading for maximum performance: ```html theme={"system"} User generated content ``` ### 4. Fallback Strategy Always have a fallback for when optimized images fail to load: ```js theme={"system"} function handleImageError(img) { const originalUrl = img.src.split('?')[0] img.src = originalUrl } ``` ```html theme={"system"} User generated content ``` The Cevoid CDN automatically handles caching and global distribution of optimized images, ensuring fast loading times for users worldwide. ### 5. Preloading Critical Images For above-the-fold images, consider preloading: ```html theme={"system"} ``` Don't preload too many images as this can actually slow down initial page load. Only preload the most critical, above-the-fold images. ## Related * [API Reference](/api-reference) * [Analytics Overview](./analytics) # Developer Docs Source: https://docs.cevoid.com/developer-docs/index Build on Cevoid with analytics implementation guides, SDK reference, MCP docs, image docs, and public API links. Use this section when you are implementing Cevoid in code. If you need Cevoid Analytics in a storefront, start with [Analytics Overview](./analytics). If you are operating Cevoid in the platform UI, use the [Help Center](/help-center). If you need public REST endpoint details, use the [API Reference](/api-reference). ## Build with Cevoid Start with the Analytics overview, then drill into gallery tracking, browser-event forwarding, session tracking, and sales or event tracking. Call Cevoid's public REST API for authentication, filtering, pagination, errors, and endpoint reference. Connect MCP-compatible AI clients to your Cevoid workspace and query analytics tools with OAuth. Optimize Cevoid CDN image URLs for responsive storefronts and different display densities. Embed Cevoid UGC galleries and cards on custom storefronts, CMS blocks, and dynamic pages. ## Choose the right docs Use product docs for platform setup, analytics concepts, widgets, integrations, and day-to-day usage. Use API-specific docs and the OpenAPI reference for request and response behavior. ## Need a full index? Use [Docs Index](./docs-index) if you want a page-by-page list of the developer docs for browsing, search, or tooling. # MCP Source: https://docs.cevoid.com/developer-docs/mcp Connect AI clients to your Cevoid workspace through the Cevoid MCP server ## Overview Use this page when you want to connect an MCP-compatible client to Cevoid and understand the current analytics-focused MCP surface. The Cevoid MCP server is Cevoid’s hosted MCP server for connecting AI clients to your Cevoid workspaces. You can use it to give tools like Claude, Cursor, and ChatGPT secure access to Cevoid context through a single MCP endpoint. The current MCP surface is Analytics. You can query UGC, Loyalty, and Profiles analytics; inspect shared metrics, dimensions, and filters; and manage reports and dashboards without leaving your AI tool. If you need direct REST integrations from your own application code, use the [API Reference](/api-reference) instead. ## When to use MCP Use MCP when you want an AI client to query analytics or set up reports and dashboards without building your own API layer first. Use the [API Reference](/api-reference) instead when you want direct REST integrations from your own application code. ## Connect Use `https://mcp.cevoid.com/mcp` as the MCP server URL. Use a client that supports MCP over streamable HTTP and OAuth-based authentication, such as Claude, Cursor, or ChatGPT. ## Quickstart 1. Open an MCP-compatible client such as Claude, Cursor, or ChatGPT. 2. Point it at `https://mcp.cevoid.com/mcp`. 3. Complete the OAuth flow for the Cevoid workspace or workspaces you want to query. 4. Start with `run-query` for direct questions, `list-reports` for discovery, or `create-report` to save a setup. ## Verify the connection Your first successful result should be a schema-first analytics answer from `run-query` or a report catalog response from `list-reports`. Try a prompt like: ```text theme={"system"} Which report should I use for widget engagement? ``` If the connection works, your MCP client should return one or more report matches instead of a generic model-only answer. ## Authentication The Cevoid MCP server uses OAuth 2.1 for authentication. Access tokens are short-lived, resource-bound to the Cevoid MCP endpoint, and carry both principal and authorized workspace identity. Clients can maintain sessions with rotating refresh tokens. * Access is scoped to the workspace or workspaces selected during authorization. * Read tools require `analytics:read`. This can include entity and profile labels used in analytics dimensions and intentional filter searches. Report and dashboard writes require explicit `analytics:write` consent. The connect page shows the requested scopes and lets you grant a subset. * Clients should use the advertised Protected Resource Metadata and include the Cevoid MCP endpoint as the OAuth `resource`. * Clients can identify themselves with OAuth Client ID Metadata Documents or Dynamic Client Registration. ## Client implementer details Use the discovery documents instead of hard-coding OAuth endpoints where your client supports discovery. * MCP endpoint: `https://mcp.cevoid.com/mcp` * OAuth resource: `https://mcp.cevoid.com/mcp` * OAuth scopes: `analytics:read`; request `analytics:write` as well when the client should manage reports or dashboards * Protected Resource Metadata: `https://mcp.cevoid.com/.well-known/oauth-protected-resource/mcp` * Authorization Server Metadata: `https://mcp.cevoid.com/.well-known/oauth-authorization-server` * Client identification: OAuth Client ID Metadata Documents are supported. Dynamic Client Registration is available as a fallback. * Token revocation: supported through the advertised OAuth revocation endpoint. Access tokens expire after 15 minutes. Refresh tokens rotate on every use and expire 30 days after the latest refresh. If a connection is not used before the refresh token expires, the client needs to reconnect through OAuth. ## Rate limits The main analytics tool calls are rate limited per authenticated principal. * `run-query`, `run-report`, and report/dashboard writes: 20 requests per minute. * `list-reports`, `get-query-schema`, `list-dimensions`, and `get-filter-values`: 60 requests per minute. Rate-limited responses include rate-limit headers and a `Retry-After` header when the client should wait before retrying. ## Available tools
Category Tool Description
Workspace list-workspaces List the workspaces this MCP session can access.
Analytics list-reports List saved analytics reports and curated presets for an authorized workspace.
run-query Query Cevoid analytics directly with a schema-first query object.
get-query-schema Inspect the supported analytics query schema for a module.
get-report Get metadata for a saved analytics report by report ID.
run-report Execute a saved analytics report by report ID and date range.
list-dimensions List the currently available analytics dimensions and metadata for a module.
get-filter-values Get valid values for a specific analytics filter.
create-report Validate and create a custom analytics report.
update-report Validate and update a custom analytics report.
Dashboard list-dashboards List analytics dashboards in a workspace.
get-dashboard Get a dashboard and its report panels.
create-dashboard Create a dashboard with validated or automatically placed panels.
update-dashboard Update a custom dashboard and its panel layout.
Workspace IDs are returned by `list-workspaces`; reuse them unchanged. Report IDs use the public `rpt_…` format and dashboard IDs use `dsh_…`. Treat these IDs as opaque and reuse returned values for later get, run, update, and dashboard-panel operations. Analytics filter values are a separate contract. A returned `value` is an opaque token valid for that filter and authorized workspace; its format may vary. Reuse it unchanged and do not treat it as a resource ID. Profile filter discovery requires at least two search characters and returns no more than 20 minimal label/token pairs. List tools return compact selection summaries; matching get tools return complete public definitions. Result counts use `returnedRowCount`, meaning rows actually returned after limits. `run-report.executedQuery` records the effective execution settings needed to interpret saved-report results. Available resources: * `cevoid://analytics/query-schema` * `cevoid://analytics/dimensions` * `cevoid://analytics/filters` * `cevoid://analytics/filter-values` * `cevoid://analytics/reports` * `cevoid://analytics/capabilities` ## Example prompts * **"What reports do I already have for UGC performance?"** Starts with `list-reports`. * **"Show me the top performing posts for the last 30 days."** Routes to `run-query`. * **"What types of analytics queries can you run for UGC?"** Uses `get-query-schema`. * **"Which workspaces can I access in this MCP session?"** Uses `list-workspaces`. * **"Create a monthly performance report and add it to a dashboard."** Uses the report and dashboard write tools after write-scope consent. ## Related * [Analytics overview](/analytics/overview) * [Authentication](/api-reference/authentication) * [Developer Docs Overview](./index) # Custom CSS Source: https://docs.cevoid.com/developer-docs/other/custom-css Use custom CSS classes to make small design tweaks to Cevoid widgets. Use this page when you need small CSS touch-ups for Cevoid widgets. Cevoid widgets are mainly styled through the platform, and most design needs can be handled in your widget settings. Every element in Cevoid widgets has a CSS class attached to it. These classes are prefixed with `.cevoid-*`. ## Find widget classes Use your browser's developer tools to explore the classes available on a live widget. 1. Open a page where your Cevoid widget is embedded. 2. Right-click the element you want to style. 3. Select **Inspect** (or **Inspect Element**) to open developer tools. 4. In the Elements panel, look for class names that start with `cevoid-` on the selected element and its parent elements. Open a popup or expand a gallery post before inspecting if you want to style elements that only appear after interaction. ## Override widget styles Add CSS for Cevoid widget classes in your site's CSS file to override the default widget styles. You may need `!important` when Cevoid's built-in styles are more specific than your site CSS. ### Hide post captions in the popup ```css theme={"system"} .cevoid-caption { display: none !important; } ``` This hides the captions of posts in the popup on both desktop and mobile. ### Hide products in popup ```css theme={"system"} .cevoid-products-wrapper { display: none !important; } ``` Class names can differ between widget types (galleries, cards, popups, and program widgets). Always inspect the element on your page to confirm the exact class before adding CSS. # Widget performance Source: https://docs.cevoid.com/developer-docs/other/widget-performance Information about UGC widget performance and its effect on your website and site speed. This is for you who has been asked by your developers about the performance of the Cevoid implementation (send them this article 😉 ) or simply if you want to learn more about the performance of our galleries and the effect the implementation has on your website. ### Let's begin! First off, the Cevoid comes from a background where speed and optimization on the web are extremely important and our holy grail. We always strive for our widgets to have the smallest effect possible on your website so that it does not interrupt, slow down or disturb the user experience in any way. *** ## Scripts When implementing Cevoid on your website, there's only one script you need to add. This script powers all Cevoid UGC widgets and makes them render. Uncached and gzipped our script (depending on what type of gallery is loaded) weights \~ 110kb. When cached, only 500 Bytes. The galleries are also code-splitted to only load the parts of the galleries that are actually needed. *** ## Images & video All images and videos that are loaded in the UGC widgets are lazy-loaded and done so asynchronously. Therefore we will never affect the initial load of a page by waiting for lots of media to load. Images in our UGC widgets and popups are scaled to fit the area where they are displayed in. We use eight different sizes ranging from original format and 1080px to thumbnails of 160px size. So if a gallery post is 400px wide, our gallery will fetch the best match in size to use. This saves bandwidth for the user and speeds up a load of images on the website! *** ## Cache All assets from Cevoid are cached. This includes scripts, images, videos, galleries, and cards. This speeds up all the requests a lot. We cache all UGC widgets at 20-minute intervals. However, if you make design changes to a gallery or card, its cache is reset. # Advanced Source: https://docs.cevoid.com/developer-docs/ugc-widgets/advanced Optional UGC widget setup for programmatic markets, CMS blocks, and custom storefront logic. Use these guides when the default embed and dynamic gallery setup is not enough. ## When to use advanced setup * URL-based market detection does not match how your storefront works * Content teams add widgets through CMS blocks instead of hard-coded embed code * You need separate language and currency markets on the same page URL ## Guides * [Programmatic Market Values](./market-values): set `data-market`, `data-market-currency`, and `data-hide-prices` * [CMS Blocks](./cms-blocks): build a reusable CMS block for galleries and cards ## Start with the basics If you have not embedded widgets yet, use [Embed Galleries and Cards](./embed) first. For product, collection, or category galleries, use [Dynamic Galleries](./dynamic-galleries). # CMS Blocks Source: https://docs.cevoid.com/developer-docs/ugc-widgets/cms-blocks Build a reusable CMS block for Cevoid UGC galleries and cards. Use this page when your site has CMS sections or blocks and you want content teams to add Cevoid widgets without editing code. This is an advanced setup path. Start with [Embed Galleries and Cards](./embed) if you have not added the base widget script yet. Build one reusable Cevoid widget block that can render either a gallery or a card. ## Recommended fields ```json theme={"system"} { "type": "GALLERY | CARD", "title": "string", "description": "string", "galleryId": "string", "cardId": "string", "width": "FULLWIDTH | CONTAINER", "widgetType": "default | product | collection | category", "productId": "string", "collectionId": "string", "categoryId": "string" } ``` Use `type` to decide whether the block renders a gallery or a card. Use `title` and `description` when the CMS should render surrounding section copy, such as "Inspiration from our community" above the widget. Use `width` when editors should choose between a full-width widget and the site's normal content width. ## Gallery widget types Use `widgetType` only for galleries: * `default`: render only `data-gallery` * `product`: add `data-product="auto"` or a specific product ID * `collection`: add `data-collection="auto"` or a specific collection identifier * `category`: add `data-category="auto"` or a specific category identifier Keep product, collection, and category identifier fields optional. If no value is provided, render `auto` for the selected dynamic gallery type. ## Rendering rules Render a gallery block like this: ```html theme={"system"}
``` Render a card block like this: ```html theme={"system"}
``` When `widgetType` is dynamic, add only the matching dynamic attribute. Do not combine `data-product`, `data-category`, and `data-collection` on the same container. ## Related * [Embed Galleries and Cards](./embed) * [Dynamic Galleries](./dynamic-galleries) * [Runtime Helpers](./runtime-helpers) # Dynamic Galleries Source: https://docs.cevoid.com/developer-docs/ugc-widgets/dynamic-galleries Render product, collection, category, and brand-aware Cevoid UGC galleries. Use dynamic galleries when the gallery content should depend on the page context. Dynamic galleries use a normal `data-gallery` value plus one additional attribute for product, collection, category, or brand. Start with [Embed Galleries and Cards](./embed) if you have not added the Cevoid widget script yet. ## Product page gallery Use `data-product="auto"` when the gallery should detect the current product from the page URL. ```html theme={"system"}
``` You can also pass a product ID directly. ```html theme={"system"}
``` The product ID must match the product ID you send to Cevoid through your product catalog. Product page galleries use fallback settings from Cevoid when the selected product has no posts, so you do not need to build separate fallback logic on your site. ## Collection page gallery Use `data-collection="auto"` when the gallery should detect the current collection from the page URL. ```html theme={"system"}
``` You can also pass a collection identifier directly. ```html theme={"system"}
``` The collection name or ID must match the collection data you send to Cevoid. ## Category page gallery Use `data-category="auto"` when the gallery should detect the current category from the page URL. ```html theme={"system"}
``` You can also pass a category identifier directly. ```html theme={"system"}
``` The category name or ID must match the category data you send to Cevoid. Category galleries prioritize posts related to the selected category, then include posts from child categories. ## Brand page gallery Use `data-brand="auto"` when the gallery should detect the current brand from the page URL. ```html theme={"system"}
``` You can also pass a brand slug directly. ```html theme={"system"}
``` ## Related * [Product feeds](/integrations/product-feeds) * [Programmatic Market Values](./market-values) * [Runtime Helpers](./runtime-helpers) # Embed Galleries and Cards Source: https://docs.cevoid.com/developer-docs/ugc-widgets/embed Add the Cevoid widget script and render UGC gallery or card containers on your site. Use this page when you need the base embed code for Cevoid UGC galleries and cards. If you are building product, collection, category, or brand-aware galleries, start here and then continue to [Dynamic Galleries](./dynamic-galleries). ## Add the widget script Add the Cevoid widget script once on pages where you render galleries or cards. You can place it in the ``, before the closing `` tag, or next to the widget container. ```html theme={"system"} ``` The script looks for elements with `id="cevoid-container"` and mounts a gallery or card based on the container's data attributes. ## Add a gallery container Use one container per widget. ```html theme={"system"}
``` ## Add a card container For cards, use `data-card` instead of `data-gallery`. ```html theme={"system"}
``` A container should render either a gallery or a card, not both. You can copy the gallery ID, card ID, or full embed code from the widget's embed dialog in Cevoid. ## Supported container attributes | Attribute | Use | | ---------------------- | --------------------------------------------------------------------------------------- | | `data-gallery` | Renders a gallery by gallery ID. | | `data-card` | Renders a card by card ID. | | `data-post` | Renders a single post when you have a post-specific embed. | | `data-product` | Filters a dynamic gallery by product. Use `auto` or a product ID. | | `data-collection` | Filters a dynamic gallery by collection. Use `auto` or a collection identifier. | | `data-category` | Filters a dynamic gallery by category. Use `auto` or a category identifier. | | `data-brand` | Filters a dynamic gallery by brand. Use `auto` or a brand slug. | | `data-country` | Overrides country detection when needed. | | `data-market` | Sets the Cevoid market used for language, product links, and default currency behavior. | | `data-market-currency` | Sets the market used for price and currency display. | | `data-hide-prices` | Hides product prices when set to `true`. | ## Next steps * Need contextual galleries: [Dynamic Galleries](./dynamic-galleries) * Need market overrides: [Programmatic Market Values](./market-values) * Need dynamic page refresh or load-state events: [Runtime Helpers](./runtime-helpers) # UGC Widgets Source: https://docs.cevoid.com/developer-docs/ugc-widgets/index Choose the right implementation path for Cevoid UGC galleries and cards. Use this section when you are implementing Cevoid UGC galleries or cards in code. If you only need to configure widgets in the platform, use [Galleries](/ugc/showcase/galleries) or [Cards](/ugc/showcase/cards) instead. Cevoid UGC widgets display content collected from customers, creators, and your brand. The widget script mounts a gallery or card into each Cevoid container on your site. ## Core concepts ### Gallery A gallery displays multiple images or videos in one widget. The content sources, layout, and design are configured in the Cevoid platform. ### Card A card displays one selected image or video. Use cards when you want to highlight a specific content piece instead of a dynamic set of posts. ### Markets Markets control widget language, prices, currency, currency formatting, and product links. By default, Cevoid detects the market from the page URL. Default market detection works best when each market has a unique URL. If multiple markets share the same URL, or your site lets visitors switch language or currency without changing URL, use [Programmatic Market Values](./market-values) under [Advanced](./advanced). ### Product catalogs Product catalogs connect product, collection, category, price, and URL data to Cevoid. Dynamic product, collection, and category galleries depend on identifiers that match the product data you send to Cevoid. Need product feed details: [Product feeds](/integrations/product-feeds) ## Core setup Add the Cevoid script and render gallery or card containers on a storefront. Use product, collection, category, or brand attributes to render context-aware galleries. Refresh widgets on dynamic pages and listen for gallery or card load state. ## Advanced Use these when the core embed path is not enough. Optional paths for programmatic markets, CMS blocks, and custom storefront logic. Override URL-based market detection for multi-market, language, currency, staging, and preview setups. Build a reusable CMS block for content teams to add Cevoid galleries and cards safely. ## Related * [Widget performance](../other/widget-performance) * [Custom CSS](../other/custom-css) * [Using Cevoid Galleries](../analytics/using-cevoid-galleries) # Programmatic Market Values Source: https://docs.cevoid.com/developer-docs/ugc-widgets/market-values Set market, currency, and price visibility values for Cevoid UGC widgets in code. Use programmatic market values when URL-based market detection is not enough. This is an advanced setup path. Start with [Embed Galleries and Cards](./embed) and [Dynamic Galleries](./dynamic-galleries) if you have not embedded widgets yet. Common cases: * one URL serves multiple markets, such as US and UK storefronts on the same path * visitors can change language or currency without a redirect * development or staging URLs do not match production market URLs ## Set the market Set `data-market` to the Cevoid market ID that should control widget language, product links, and default currency behavior. ```html theme={"system"}
``` For example, if your storefront detects an English and USD session, set `data-market` to the Cevoid market ID for that language and market setup. ## Set currency separately Set `data-market-currency` when prices and currency should come from a different market than the main `data-market`. ```html theme={"system"}
``` This keeps language and product links from `data-market`, while price and currency come from `data-market-currency`. ## Hide prices Set `data-hide-prices="true"` when product prices should be hidden in the widget. ```html theme={"system"}
``` ## Related * [Embed Galleries and Cards](./embed) * [Dynamic Galleries](./dynamic-galleries) * [Products and markets](/general/products-markets) # Runtime Helpers Source: https://docs.cevoid.com/developer-docs/ugc-widgets/runtime-helpers Refresh Cevoid UGC widgets and react to gallery or card load state on dynamic pages. Use runtime helpers when your storefront changes widget containers after the initial page load, or when your code needs to react to widget load state. ## Refresh widgets on dynamic pages The script mounts widgets when it loads. If your site adds or changes Cevoid containers after the initial page load, call `window.cevoid.reloadAll()` after updating the DOM. ```js theme={"system"} if (window.cevoid?.reloadAll) { window.cevoid.reloadAll(); } ``` Use this for single-page apps, AJAX-loaded sections, product variant changes, and CMS tabs that reveal widget containers after load. ## Check widget load state Cevoid exposes gallery and card load state on `window.cevoid`. ```js theme={"system"} const galleryId = "GALLERY_ID"; if (window.cevoid?.galleries?.[galleryId]?.hasContent) { console.log("Gallery has content."); } else { console.log("Gallery has not loaded or has no content."); } ``` Cards use the same pattern under `window.cevoid.cards`. ```js theme={"system"} const cardId = "CARD_ID"; if (window.cevoid?.cards?.[cardId]?.hasContent) { console.log("Card has content."); } ``` This is useful when you want to hide a section if a dynamic gallery has no posts. ## Listen for widget load events Use widget load events when your code needs to react as soon as a gallery or card finishes loading. ### Gallery loaded ```js theme={"system"} window.addEventListener("cevoid-gallery-loaded", (event) => { const galleryId = event.detail.gallery; const numberOfPosts = event.detail.numberOfPosts; if (numberOfPosts > 0) { console.log(`Gallery ${galleryId} has content.`); } else { console.log(`Gallery ${galleryId} has no content.`); } }); ``` ### Card loaded ```js theme={"system"} window.addEventListener("cevoid-card-loaded", (event) => { const cardId = event.detail.card; console.log(`Card ${cardId} has loaded.`); }); ``` Set up event listeners before loading dynamic widgets when possible, especially if your script needs to react to the first widget load. ## Related * [Embed Galleries and Cards](./embed) * [CMS Blocks](./cms-blocks) * [Using Cevoid Galleries](../analytics/using-cevoid-galleries) # Labels Source: https://docs.cevoid.com/general/labels Create custom labels to categorize posts and profiles. Related articles: [Posts](/ugc/manage/posts), [Profiles](/general/profiles/profiles), [Segments](/general/profiles/segments), [Galleries](/ugc/showcase/galleries) Labels let you define custom categorizations for posts and profiles. Use them to organize content and your brand community beyond Cevoid's built-in categorizations. Navigate to [Settings -> Labels](https://app.cevoid.com/settings/labels) to manage your labels. Labels table | Label type | Use for | | --------------------------------- | ------------------------------------ | | [Post labels](#post-labels) | Organize posts and build UGC widgets | | [Profile labels](#profile-labels) | Organize your brand community | *** ## Post labels Post labels let you categorize your posts freely. Use them to: * Filter your [Library and Inbox](/ugc/manage/library-and-inbox) * Create [Galleries](/ugc/showcase/galleries) that use the label as a content source * Create [dynamic email widgets](/ugc/showcase/email-widgets) In most cases, you don't need to create post labels related to your product catalog. Instead, add product tags to a post to automatically relate the post to the product, its categories, and product collections. *** ### Create a post label **From the Labels view:** 1. Navigate to [Settings -> Labels](https://app.cevoid.com/settings/labels) 2. Select *Post* as label type 3. Enter the name of your new post label 4. Optional: Add a color or emoji to make your label more visually unique 5. Click **Create** **From the Post view:** 1. Open a post from the [Library or Inbox](/ugc/manage/library-and-inbox) 2. Click **Add label** 3. Enter the name of your new post label 4. Click **New label:** (the name you entered) *** ## Profile labels Profile labels let you categorize your profiles freely. Use them to: * Filter your [Profiles](/general/profiles/profiles) overview * As filter criteria for custom [segments](/general/profiles/segments) *** ### Create a profile label **From the Labels view:** 1. Navigate to [Settings -> Labels](https://app.cevoid.com/settings/labels) 2. Select *Profile* as label type 3. Enter the name of your new profile label 4. Optional: Add a color or emoji to make your label more visually unique 5. Click **Create** **From the Profile view:** 1. Navigate to a profile page 2. Click **Add label** under *Properties* in the sidebar 3. Enter the name of your new profile label 4. Click **New label:** (the name you entered) # Legal policies Source: https://docs.cevoid.com/general/legal Configure consent policies for content submissions and program opt-ins. Related articles: [Upload forms](/ugc/collect/upload-forms), [UGC from Instagram](/ugc/collect/ugc-from-instagram), [Challenges](/program/activities/challenges), [Member opt-in & enrollment](/program/program-setup/member-opt-in-enrollment) Legal policies help you collect consent from customers when they submit content or join your rewards program. Configure the messages your customers see and ensure compliance with regional requirements. Navigate to [Settings -> Legal](https://app.cevoid.com/settings/legal) to manage your policies. Legal policy configuration Policies can be localized for different jurisdictions to align with regional legal requirements. Only activated policies are displayed to customers. *** ## Available policies | Policy | Description | | -------------------------- | ---------------------------------------------------------------------------------------------- | | **Content consent** | Displayed when someone submits content through upload forms, DM rights requests, or challenges | | **Program opt-in consent** | Displayed when someone joins your rewards program through a Cevoid widget | | **Competition terms** | Optional terms for challenges that are competitions | *** ## Content consent The content consent policy ensures that anyone submitting content to your brand approves your UGC policy and grants permission to use their content. This protects both you and the creator by making the terms of use clear upfront. Include a link to your website where the full content consent terms are available. See [Content consent example](/resources/content-consent-example) for sample copy you can adapt. **Where it's displayed:** | Solution | When displayed | | ----------------------------------------------------- | ------------------------------------------ | | [Upload forms](/ugc/collect/upload-forms) | When someone submits a post | | [DM rights requests](/ugc/collect/ugc-from-instagram) | When approving a rights request | | [Challenges](/program/activities/challenges) | When submitting content-related challenges | ### Activate content consent 1. Navigate to [Settings -> Legal](https://app.cevoid.com/settings/legal) 2. Open **Content consent** 3. Select Simple text or Checkboxes based on your requirements 4. Enter your message and add any required links 5. Click **Publish** 6. Repeat for any additional jurisdictions you need *** ## Program opt-in consent The program opt-in consent policy ensures that members agree to your program terms before participating in any activities. This is essential for transparency and helps you stay compliant with consumer protection regulations. You can also collect marketing consent at the same time, streamlining the opt-in experience while keeping consent properly documented. Include a link to your website where the full program terms are available. **Where it's displayed:** | Solution | When displayed | | ------------------- | ------------------------------------------------- | | All program widgets | When a new member opts in to your rewards program | This policy is only enforced through Cevoid widgets. Members may opt in through other methods depending on your [opt-in settings](/program/program-setup/member-opt-in-enrollment). ### Activate program opt-in consent 1. Navigate to [Settings -> Legal](https://app.cevoid.com/settings/legal) 2. Open **Program opt-in consent** 3. Select Simple text or Checkboxes based on your requirements 4. Enter your message and add any required links 5. Optional: Add a marketing communication message to collect email consent at the same time * Simple text automatically approves everyone for marketing communications * Checkboxes only approves members who explicitly check the marketing box 6. Click **Publish** 7. Repeat for any additional jurisdictions you need *** ## Competition terms When running challenges that are formal competitions, you may need to display specific legal terms beyond your standard content consent. The competition terms policy lets you add these requirements to specific challenges. Include a link to your website where the full competition terms are available. Competition terms are not automatically displayed on all challenges since not every challenge is a competition. You need to enable them per challenge. **Where it's displayed:** | Solution | When displayed | | -------------------------------------------- | --------------------------------------------------------- | | [Challenges](/program/activities/challenges) | When submitting challenges with competition terms enabled | ### Activate competition terms 1. Navigate to [Settings -> Legal](https://app.cevoid.com/settings/legal) 2. Open **Competition terms** 3. Select Simple text or Checkboxes based on your requirements 4. Enter your message and add any required links 5. Click **Publish** 6. Repeat for any additional jurisdictions you need ### Enable competition terms on a challenge 1. Edit the challenge 2. Click **General Settings** 3. Toggle on *Competition Terms* *** ## Consent options Each policy can be configured to use either checkboxes or simple text. You can use different options for different jurisdictions based on local requirements. | Option | How it works | | --------------- | ------------------------------------------------------------------------------------------------------- | | **Checkboxes** | Visitors must tick the checkbox before they can proceed. This provides explicit consent documentation. | | **Simple text** | Visitors see the message and can continue without taking action. The act of proceeding implies consent. | The only exception is the marketing communication option in program opt-in consent, which always uses an optional checkbox regardless of your main consent setting. *** ## Jurisdictions Different markets often have different legal requirements. Jurisdictions let you configure separate policy versions for different regions. Cevoid widgets automatically display the correct policy based on the [market](/general/products-markets) they're shown in. You only need to set up jurisdictions if you want different policies for different markets. The default policy applies to all markets that don't have a specific jurisdiction assigned. ### Create a jurisdiction 1. Navigate to [Settings -> Legal](https://app.cevoid.com/settings/legal) 2. Click **Add jurisdiction** 3. Name the jurisdiction (e.g., "EU" or "UK") 4. Select which markets should use this jurisdiction's policies 5. Click **Create** 6. Configure the jurisdiction-specific policies # Products & Markets Source: https://docs.cevoid.com/general/products-markets Connect your product catalog and localize widgets for each market. Related articles: [Translations](/general/translations), [Program introduction](/program/introduction), [Shopify integration](/integrations/shopify), [Product feeds](/integrations/product-feeds) Markets connects Cevoid to your ecommerce store and ensures your widgets display the right language, currency, and product information for each version of your website. This applies to both UGC widgets and your rewards program. Navigate to [Settings -> Products & Markets](https://app.cevoid.com/settings/products-and-markets) to configure your markets. *** ## What is a market? A market in Cevoid represents a localized version of your store - a unique combination of domain, language, and currency. If you sell to customers in different countries or regions, each localized storefront is a separate market. For example, if you have: * `cevoidsupply.com` (English, USD) * `cevoidsupply.com/fr` (French, EUR) * `cevoidsupply.de` (German, EUR) Each of these is a separate market in Cevoid. Once your markets are set up, all Cevoid widgets automatically display the correct language, prices, and product links based on which market they're shown in. The experience matches the rest of your website seamlessly. *** ## How localization works When a visitor views a Cevoid widget, we detect which market they're on based on the URL. For stores without market-specific URLs, the market can be set programmatically or detected automatically through our Shopify integration. The widget then displays: **UGC widgets:** * All consumer-facing copy displayed in the market's language * Captions translated into the market's language * Product names from that market's product catalog * Prices in the correct currency with proper formatting * Product links pointing to the correct localized product pages * Accessibility text (alt text, video captions, video descriptions) * Measurement profile properties displayed in the correct unit (metric or imperial) **Rewards program widgets:** * All consumer-facing copy displayed in the market's language * Points-per-currency rates adjusted for purchase incentives * Discount code rewards presented and created in local currency * Measurement profile properties collected in the correct unit (metric or imperial) If a visitor is on a URL that doesn't match any market, the default market is used as a fallback. *** ## Create a market Your first market is created automatically when you connect your store. Create additional markets for each localized version of your website. 1. Navigate to [Settings -> Products & Markets](https://app.cevoid.com/settings/products-and-markets) 2. Click **Add market** 3. Configure the market settings 4. Connect the product catalog 5. Click **Save** For platform-specific setup instructions, see: [Shopify integration](/integrations/shopify), [WooCommerce integration](/integrations/woocommerce), or [Product feeds](/integrations/product-feeds) for other platforms. *** ## Market settings ### Market details These settings tell Cevoid how to identify and configure the market. | Setting | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------- | | *Domain* | The URL for this market (e.g., `cevoidsupply.com` or `cevoidsupply.com/fr`) | | *Country/Region* | The country or region this market serves | | *Language* | The market's language. Also adds this language to [Translations](/general/translations) | | *Currency* | The currency used for prices | | *Title* | Internal name to help your team identify the market | | *Default* | Enable for your primary market. Used as fallback when no other market matches, and used when tagging products in posts | *** ### Currency options Control how prices and currency symbols appear. Cevoid applies best practices for your selected currency automatically, but you can customize these settings. | Setting | Description | | -------------------- | ------------------------------------------------------- | | *Hide prices* | Hide product prices in all UGC widgets | | *Currency display* | Format of the currency (e.g., "USD" or "\$") | | *Currency position* | Show currency before or after the price | | *Display 2 decimals* | Show two decimal places (e.g., $43.50 instead of $43.5) | | *Decimal delimiter* | Symbol separating decimals (comma or period) | | *Thousand separator* | Symbol separating thousands (space, comma, or period) | | *Round prices* | Round to whole numbers, removing decimals | *** ### Advanced settings | Setting | Description | Options | | -------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | *Non-available products* | How to handle products that don't exist in this market | **Show as normal**: Link to default market's product page. **Show as unavailable**: Display "Unavailable" text, no link. **Hide** (default): Don't show the product tag | | *Products out of stock behavior* | How to handle products marked out of stock | **Show product as normal** (default): Display without indication. **Hide product**: Don't show the product tag. **Show out-of-stock text**: Display "Out of stock" label | | *Custom ID* | Set a custom identifier for the market, useful for API integrations | | | *Staging domain* | Add a staging URL to test and preview this market before going live | | *** ## Product catalog sync Cevoid continuously syncs your product catalog for each market to ensure product information stays up to date and new products are available for tagging. To trigger a manual sync: 1. Navigate to [Settings -> Products & Markets](https://app.cevoid.com/settings/products-and-markets) 2. Click **Sync products** Product syncs typically complete within a few minutes. Large catalogs may take longer. # Profile data & event sharing Source: https://docs.cevoid.com/general/profiles/profile-data-event-sharing Share profile data and events from Cevoid with your CRM and ecommerce platforms to personalize communication and storefronts. Related articles: [Profiles](/general/profiles/profiles), [Profile properties](/general/profiles/profile-properties), [Program emails & triggers](/program/program-setup/program-emails-and-triggers), [Klaviyo](/integrations/klaviyo), [Voyado](/integrations/voyado), [Shopify](/integrations/shopify) Profile data and events from Cevoid can be shared with your CRM and ecommerce platforms. This lets you personalize your storefronts, build segments, trigger email flows, and tailor communication based on information collected through Cevoid. Profile data and event sharing requires an email address. The profile must have an email in Cevoid, and a matching email must exist in your CRM or ecommerce platform for syncing to occur. Emails are collected automatically for all [rewards program](/program/introduction) interactions and when UGC is uploaded via your [upload forms](/ugc/collect/upload-forms). *** ## Profile data Profile data is information about a profile that stays in sync. When data changes in Cevoid, it's automatically updated in your connected platforms. ### Default fields These fields are available for all profiles and are updated automatically by Cevoid. | Field | Description | | ----------------------------------- | ---------------------------------------------------- | | **Cevoid: Social Instagram Handle** | The profile's Instagram username | | **Cevoid: Joined Program At** | Date the profile joined your rewards program | | **Cevoid: Points** | Current points balance | | **Cevoid: Program Member** | Whether the profile is a program member (true/false) | | **Cevoid: Tier Icon** | URL to the profile's current tier icon | | **Cevoid: Tier Id** | Unique identifier for the profile's current tier | | **Cevoid: Tier Name** | Name of the profile's current tier | | **Birthdate** | The profile's birthdate | ### Custom properties Any custom profile properties you create in Cevoid can also be shared with your connected platforms. Custom properties appear in the data sharing settings with a "Custom property" label. Learn more about creating custom properties in [Profile properties](/general/profiles/profile-properties). *** ## Events Events are triggers sent to your CRM when something happens in Cevoid. Use them to build email flows and automations. Each event includes relevant data that can be used in your emails. ### Program events Events triggered by rewards program activity, such as when a member joins your program, earns a tier, or receives a reward. These events are covered in detail in [Program emails & triggers](/program/program-setup/program-emails-and-triggers), including all available events, payload examples, and email flow suggestions. ### UGC events Events triggered by content-related actions. | Event | Trigger | | ------------------------------- | -------------------------------------------------------- | | **Cevoid: Instagram Mentioned** | When a profile mentions your Instagram account in a post | | **Cevoid: Instagram Tagged** | When a profile tags your Instagram account in a post | | **Cevoid: Post Created** | When a profile creates a post | ```json theme={"system"} { "caption": "Caption", "mediaId": "1", "mediaType": "IMAGE", "mediaUrl": "https://cdn.cevoid.com/posts/1.jpg", "permalink": "https://www.instagram.com/p/1234567890/", "user": { "username": "cevoid_test_user" }, "thumbnail": "https://cdn.cevoid.com/posts/1.jpg" } ``` ```json theme={"system"} { "caption": "Caption", "mediaId": "1", "mediaType": "IMAGE", "mediaUrl": "https://cdn.cevoid.com/posts/1.jpg", "permalink": "https://www.instagram.com/p/1234567890/", "user": { "username": "cevoid_test_user" }, "thumbnail": "https://cdn.cevoid.com/posts/1.jpg" } ``` ```json theme={"system"} { "media": { "aspectRatio": 1, "filename": "1.jpg", "fileSize": 200, "hash": "1234567890", "location": "https://cdn.cevoid.com/posts/1.jpg", "hasAudio": false, "removedAudio": false, "thumbnail": "https://cdn.cevoid.com/posts/1.jpg", "videoLength": 0 }, "type": "IMAGE" } ``` *** ## Where data and events can be shared ### CRM platforms Share profile data and events to build segments, personalize emails, and trigger automated flows. | Platform | Profile data | Events | Documentation | | -------------------------------- | ----------------- | -------------------- | -------------------------------- | | **Klaviyo** | Custom properties | Metrics for flows | [Klaviyo](/integrations/klaviyo) | | **Voyado** | Contact fields | Contact interactions | [Voyado](/integrations/voyado) | | **General implementation (API)** | Via API | Via webhooks | Private beta | ### Ecommerce platforms Share profile data to personalize storefronts and build customer segments. Events are not available for ecommerce platforms. | Platform | Profile data | Documentation | | -------------------------------- | ---------------------------- | -------------------------------- | | **Shopify** | Customer metafields and tags | [Shopify](/integrations/shopify) | | **General implementation (API)** | Via API | Private beta | *** ## How sharing works ### Automatic sync Once you enable a field or event for sharing, Cevoid handles everything automatically. Profile data syncs whenever it changes. Events are sent in real-time when they occur. ### Historical sync If you enable data sharing after you already have profiles in Cevoid, you can trigger a sync of historical profiles from the integration settings. This ensures all existing profiles are updated with the selected fields. ### Test sync Before going live, you can test that everything is working correctly. For profile data, create a test profile to verify fields are syncing. This creates a fake profile in your connected platform with sample data for all enabled fields. For events, send a test event to verify the integration is working. This triggers the event on a test profile so you can preview the payload in your CRM. *** ## Multiple CRM accounts or stores This section is relevant if you have multiple CRM accounts connected (e.g., separate Klaviyo accounts for different regions) or multiple ecommerce stores connected (e.g., separate Shopify stores for different markets), or both. If you have only one CRM account and one ecommerce store connected, profiles are synced regardless of which market they belong to. All profiles with an email that exists in your CRM or ecommerce platform are automatically synced. ### What market a profile is connected to The first time a profile opts in or takes an action in one of your program widgets, or places an order that is tracked through Cevoid, Cevoid checks what market this happened on and associates their profile with that market. Their profile data and events are then shared with the CRM account and ecommerce store related to that market. You can also manually change a profile's market from their profile page. If no market has been detected, profiles are synced to connections related to your primary market. ### How sharing works with multiple connections To avoid duplicate communication, Cevoid only syncs each profile to the CRM account or store associated with their market. For profiles whose email doesn't already exist in your CRM, you can configure whether Cevoid should create new profiles automatically. By default, new profiles are not created to avoid affecting your platform usage without your knowledge. *** ## Configuring data and event sharing Profile data and event sharing is configured on each integration's settings page: 1. Navigate to **Settings -> Integrations** 2. Select the integration you want to configure 3. Find the **Profile data** or **Events** section 4. Toggle on the fields or events you want to sync 5. Click **Save** For detailed instructions, refer to the documentation for your specific integration: * [Klaviyo](/integrations/klaviyo) * [Voyado](/integrations/voyado) * [Shopify](/integrations/shopify) # Profile properties Source: https://docs.cevoid.com/general/profiles/profile-properties Collect and manage profile data through your rewards program. Create custom properties to gather information specific to your brand. Related articles: [Profiles](/general/profiles/profiles), [Profile data & event sharing](/general/profiles/profile-data-event-sharing), [Activities overview](/program/activities/overview), [Segments](/general/profiles/segments) Profile properties store data about your profiles. Use them to collect information through your rewards program activities, build segments, personalize communication, and share data with your integrations. Navigate to [Settings -> Properties](https://app.cevoid.com/settings/properties) to manage your profile properties. *** ## Default properties Cevoid provides built-in properties that are commonly used by ecommerce brands. These properties cannot be deleted. | Property | Type | Description | | ------------- | -------- | -------------------------------- | | **Country** | Country | The profile's country | | **City** | Text | The profile's city | | **Language** | Language | The profile's preferred language | | **Birthdate** | Date | The profile's birthdate | *** ## Custom properties Create your own properties to collect information specific to your brand. Custom properties can be used in activities to collect data from members, and shared to your connected integrations. ### Property types | Type | Description | Settings | | ---------- | ------------------------------------------ | --------------------------------------------------------------------------------------------- | | **Choice** | Let members select from predefined options | Single or multi select, display as text or color | | **Number** | Collect numeric values | Optional min and max value | | **Height** | Collect height measurements | Metric: Centimeter. Imperial: Foot & Inch | | **Weight** | Collect weight measurements | Metric: Tonne, Kilogram, Gram, Milligram. Imperial: Pound, Ounce | | **Length** | Collect length measurements | Metric: Kilometer, Meter, Decimeter, Centimeter, Millimeter. Imperial: Mile, Yard, Foot, Inch | | **Link** | Collect URLs | Optional regex pattern for validation | ### Choice property settings When creating a Choice property, configure how members can select options: | Setting | Description | | ----------------- | ------------------------------------------------------------- | | *Choice type* | Single select (one option) or Multi select (multiple options) | | *Multi selection* | For multi select: Unlimited, Exact number, or Range | | *Display type* | Text or Color (color shows a color swatch) | | *Options* | The choices available to members | Existing options cannot be edited or deleted once created. You can add new options and reorder all options. ### Measurement properties Height, Weight, and Length properties collect data in the measurement system configured in your [workspace settings](https://app.cevoid.com/settings). When members input measurement data through program activities, they can enter values in the measurement system of their market and can switch to the other system if they prefer. Collected data is converted to your workspace's default measurement system before saving. When measurement data is displayed to members, it's shown in the measurement system of their market. *** ## Create a custom property 1. Navigate to [Settings -> Properties](https://app.cevoid.com/settings/properties) 2. Click **Create property** 3. Enter a name for the property 4. Select a type 5. Configure type-specific settings 6. Under *Integration sync*, toggle on the integrations you want to sync this property to 7. Click **Save changes** *** ## Edit a property 1. Navigate to [Settings -> Properties](https://app.cevoid.com/settings/properties) 2. Click the **...** menu on the property row 3. Click **Edit** 4. Make your changes 5. Click **Save changes** If a property is currently used by active profiles, some settings cannot be changed. You can still add new options and reorder them. *** ## Delete a property 1. Navigate to [Settings -> Properties](https://app.cevoid.com/settings/properties) 2. Click the **...** menu on the property row 3. Click **Delete** 4. Confirm the deletion Deleting a property removes it from all profiles and any activities using it. This cannot be undone. *** ## Collecting properties Profile properties are collected through your rewards program activities. Add a Profile properties task to a [single-task activity](/program/activities/single-task-activities) or [challenge](/program/activities/challenges) to ask members to provide their information. Members can also have their properties edited manually by your team from their [profile page](/general/profiles/profiles). *** ## Using properties ### Segments Use profile properties as filter criteria when building [segments](/general/profiles/segments). For example, create a segment of members in a specific country or with a particular preference. ### Profile page Properties appear in the Profile properties section on each profile's Overview tab. Your team can view and edit values directly from the profile page. ### Profiles overview Custom properties are available as columns in the [Profiles overview](https://app.cevoid.com/profiles). Click **Columns** to add them to your table view. ### Data sharing Profile properties can be shared with your connected integrations. Toggle on the integrations you want to sync to when creating or editing a property, or configure data sharing from your integration settings. Learn more in [Profile data & event sharing](/general/profiles/profile-data-event-sharing). ### UGC galleries Profile properties can be highlighted alongside UGC posts in your galleries, letting you showcase member information with their content. # Profiles Source: https://docs.cevoid.com/general/profiles/profiles View and manage your customers, creators, and program members. Profiles are created automatically from purchases, program signups, and content submissions. Related articles: [Profile properties](/general/profiles/profile-properties), [Profile data & event sharing](/general/profiles/profile-data-event-sharing), [Segments](/general/profiles/segments), [Profile labels](/general/labels) Cevoid maintains a complete record of each person in your workspace. A profile is not accessible by the person, but is instead there to help your team keep your brand community organized. A profile is created the first time an individual uploads a post, approves a rights request, opts into your program, makes a purchase, or is manually added by your team. From there, Cevoid maintains a single profile for each person, combining their UGC, program activity, purchases, and collected data in one place. Navigate to [Profiles](https://app.cevoid.com/profiles) to view and manage your profiles. *** ## Profiles overview The profiles overview displays all profiles in your workspace as a table. Use segments, filters, and search to find specific profiles. ### Segments Segment tabs appear above the table, letting you quickly switch between different groups of profiles. The **All** tab shows every profile in your workspace. Learn more about creating and managing segments in [Segments](/general/profiles/segments). ### Search and filter Use the search bar to find profiles by name, email, or social media handle. Click **+ Filter** to filter profiles by attributes like tier, points balance, activity count, or profile properties. ### Customize columns Click **Columns** to choose which data appears in the table. Available columns include: | Column | Description | | -------------------- | ------------------------------------ | | **Name** | Profile name | | **Email** | Email address | | **Post** | Number of posts in the library | | **Inbox** | Number of posts in the inbox | | **Instagram** | Instagram handle | | **Instagram rights** | Content rights status | | **Points** | Current points balance | | **Tier** | Current tier | | **Activities** | Number of completed activities | | **Spend** | Total spend from tracked orders | | **Orders** | Number of tracked orders | | **Assignee** | Team member assigned to this profile | | **Country** | Profile's country | | **Birthdate** | Profile's birthdate | | **Language** | Profile's language | | **Last activity** | Date of most recent activity | | **Program opt-in** | Date they joined the program | | **Created** | Date the profile was created | Custom profile properties also appear as column options. Click **Set as default** to save your column selection for your team. Click **Reset to default** to restore the workspace default. *** ## Profile page Click a profile name to open their profile page. The page has four tabs: Overview, UGC, Rewards program, and Activity. ### Overview tab The Overview tab shows profile information and a summary of their engagement. **Profile information** | Field | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------- | | **Name** | The profile's display name | | **Email** | Email address | | **Assignee** | Team member responsible for this profile. Used to help your team stay organized. | | **Labels** | Profile labels added by your team. Learn more about [profile labels](/general/labels#profile-labels). | | **Email notifications** | Which emails they receive (Confirmations, Reminders) | | **Notes** | Internal notes from your team | | **Profile created** | When the profile was created | **Profile properties** Collected data about the profile. You can define your own custom properties to collect additional information. Click a value to edit it. Learn more in [Profile properties](/general/profiles/profile-properties). **Socials** | Field | Description | | -------------------- | -------------------------------------- | | **Instagram** | Their Instagram handle | | **Instagram rights** | Content rights setting for their posts | | **TikTok** | Their TikTok handle | | **X.com** | Their X (Twitter) handle | **Integrations** Shows sync status with connected platforms: | Field | Description | | ----------- | ----------------------------------- | | **Market** | Which market the profile belongs to | | **Shopify** | Sync status with Shopify | | **Klaviyo** | Sync status with Klaviyo | **Program membership** If the profile is a program member, this section shows: | Field | Description | | ----------------------- | ---------------------------- | | **Member since** | Date they joined the program | | **Current tier** | Their tier in the program | | **Point balance** | Current points available | | **Total points earned** | Lifetime points earned | | **Total spend** | Total from tracked orders | | **Total orders** | Number of tracked orders | Actions available: * **See engagement** - View detailed engagement metrics * **Adjust points** - Manually add or remove points * **Change tier** - Manually change their tier If the profile is not a program member, you can click **Opt in to program** to add them manually. **Latest content** Thumbnails of recent UGC from this profile. Click **See all content** to view all their content. **Recent activity** A feed of recent actions related to this profile, such as tier changes, activity completions, and property updates. ### UGC tab A content portfolio for this profile. Displays all posts associated with them, including approved content in your library, items in your inbox, and content from their connected social accounts. ### Rewards program tab Shows detailed program information: * **Stats**: Member since, Completed activities, Point balance, Points earned, Spend, Orders * **Submissions**: Table of all activity submissions with ID, Activity name, Type, Status, Tasks completed, and Submitted date * **Rewards**: Table of all rewards received with Reward name, Type, Status, Value, and Awarded date ### Activity tab A complete log of all actions related to this profile, including: * Tier changes * Activity participation * Label changes * Property updates * Settings changes * Points adjustments * Content status changes *** ## Create a profile Manually create profiles for customers or members. 1. Navigate to [Profiles](https://app.cevoid.com/profiles) 2. Click **Create profile** 3. Fill in the profile details: | Field | Description | | ------------------------------ | ---------------------------------------------------------------------------------------------------- | | **Instagram username** | Optional. Used to identify content from Instagram. | | **Email address** | Optional. Used for communication and to identify content from direct uploads. | | **Display name** | Shown as name for non-social media posts. | | **Instagram rights** | Appears when an Instagram username is entered. Select how you want to access this profile's content. | | **Manually opt-in to program** | Check to add them to your rewards program. | 4. Click **Create profile** *** ## Edit a profile Open a profile and click any editable field to update it. Changes are saved automatically. To edit profile properties, click the value in the Profile properties section. A dialog appears where you can enter the new value. *** ## Assign a profile Assign profiles to team members to track who's responsible for managing relationships. 1. Open the profile 2. Click **Unassigned** (or the current assignee) next to Assignee 3. Select a team member *** ## Profile actions Click **More** in the top right of a profile page to access additional actions: | Action | Description | | ----------------------- | ----------------------------------------------------- | | **Copy profile ID** | Copy the profile's unique ID to your clipboard | | **Create gallery** | Create a UGC gallery featuring this profile's content | | **Merge with...** | Merge this profile with another profile | | **Remove from program** | Remove the member from your rewards program | | **Delete** | Permanently delete the profile | *** ## Merge profiles If the same person has multiple profiles, merge them into one. This is useful when a customer has interacted with your brand through different channels or email addresses. 1. Open one of the profiles you want to merge 2. Click **More** -> **Merge with...** 3. Select the other profile from the dropdown 4. Click **Next step** 5. Review the merge summary and select which values to keep for each field 6. Click **Merge** The merge summary shows both profiles side by side with their data. Select the values you want to keep for the merged profile. One profile will be kept and the other will be deleted, with the selected data merged into the remaining profile. Merging profiles cannot be undone. The profile you merge into will be permanently deleted. *** ## Delete a profile Deleting a profile permanently removes them from your workspace. 1. Open the profile 2. Click **More** -> **Delete** 3. Confirm the deletion Deleting a profile will: * Remove them from your rewards program * Delete their content from your workspace * Clear all their profile data Their activity submissions will remain but will reference an anonymized profile. # Segments Source: https://docs.cevoid.com/general/profiles/segments Group profiles dynamically based on filter criteria. Use segments to organize your brand community and control access to activities and rewards. Related articles: [Profiles](/general/profiles/profiles), [Profile properties](/general/profiles/profile-properties), [Activities overview](/program/activities/overview), [Redeemable rewards](/program/redeemable-rewards) Segments group profiles dynamically based on filter criteria. As profiles change, they're automatically added or removed from segments based on whether they match the criteria. Use segments to organize your brand community, track different groups, and control who can access specific activities and rewards. Navigate to [Profiles -> Segments](https://app.cevoid.com/profiles/segments) to manage your segments. Your segments appear as tabs in the Profiles overview, letting you quickly switch between different groups. *** ## Standard segments Cevoid provides three pre-defined segments that correspond to the main modules: | Segment | Description | | -------------------- | ------------------------------------------------------ | | **Content creators** | All profiles with at least one post connected to them | | **Program members** | All profiles that have opted into your rewards program | | **Customers** | All profiles with at least one order tracked by Cevoid | Standard segments cannot be edited or deleted. *** ## Custom segments Create your own segments to group profiles based on any combination of filter criteria. Custom segments can use profile properties, labels, activity completion, tier status, and more. ### Create a segment 1. Navigate to [Profiles -> Segments](https://app.cevoid.com/profiles/segments) 2. Click **Create segment** 3. Enter a name for your segment 4. Optional: Add an emoji to make it visually distinct 5. Apply your filter criteria 6. Click **Create** ### Edit a segment 1. Navigate to [Profiles -> Segments](https://app.cevoid.com/profiles/segments) 2. Click on the segment you want to edit 3. Apply your new filter criteria 4. Click **Save** ### Delete a segment 1. Navigate to [Profiles -> Segments](https://app.cevoid.com/profiles/segments) 2. Click on the segment you want to delete 3. Click **Delete** 4. Confirm the deletion *** ## Using segments ### Profiles overview Segments appear as tabs above the profiles table. Click a segment tab to view only the profiles that match its criteria. ### Restrict activities and rewards Make an activity or redeemable reward exclusive to specific segments. When restricted, only members who belong to the selected segments can see and access the activity or reward. Learn more in [Activities overview](/program/activities/overview) and [Redeemable rewards](/program/redeemable-rewards). ### Data sharing When syncing historical profile data to your integrations, you can limit the sync to profiles in specific segments. Learn more in [Profile data & event sharing](/general/profiles/profile-data-event-sharing). # Translations Source: https://docs.cevoid.com/general/translations Manage translations for all consumer-facing copy across your markets. Related articles: [Products & Markets](/general/products-markets), [UGC introduction](/ugc/introduction), [Rewards program introduction](/program/introduction), [Accessibility](/resources/accessibility) All consumer-facing content is automatically translated for each of your market languages. Write copy in your primary language anywhere in the platform, and Cevoid's AI translates it to all your other languages when you save. In most cases, you won't need to visit the Translations page at all. Navigate to [Settings -> Translations](https://app.cevoid.com/settings/translations) to view and adjust translations. Translations *** ## Automatic translations Cevoid's AI handles all translations automatically: **Widget copy** - All text in your UGC and rewards program widgets is translated when you create or edit it. This includes activity descriptions, reward names, button labels, and any custom copy you write. **Post content** - Captions and accessibility text (alt text, video captions, video descriptions) are translated automatically for each market. Hashtags and @mentions in captions are kept in their original form. You can still make manual adjustments to any translation if needed. *** ## Set a custom tone Give Cevoid's AI language-specific guidelines to ensure translations match your brand voice for each market. 1. Navigate to [Settings -> Translations](https://app.cevoid.com/settings/translations) 2. Click **Localize** on a language 3. Click the menu icon next to the language name 4. Click **Language settings** 5. Enter your custom tone guidelines 6. Click **Save** *** ## Primary language Your workspace's primary language is the source for all translations. To change your primary language: 1. Navigate to [Settings -> General](https://app.cevoid.com/settings) 2. Select the new language under *Primary language* 3. Click **Save changes** *** ## Where do I write consumer-facing copy? Copy is written in different places depending on what you're editing: **Program content** - Activities, rewards, tiers, and other program content is written where you create it. Navigate to the activity, reward, or tier and edit the copy there. **Navigation and general copy** - Button labels, headings, and other general copy is pre-written but can be adjusted. Edit your default language in [Settings -> Translations](https://app.cevoid.com/settings/translations), and changes are automatically translated across all languages. **UGC copy** - UGC widget copy is shared across multiple interfaces, so it's edited in the same place as navigation and general copy. Texts that need to be edited elsewhere are marked with an **Edit in source** button in the translation editor. *** ## Navigate the translations page Click **Localize** on any language to open the translation editor. The sidebar shows: * **Customer-facing texts** - Widget copy and other consumer-facing content * **Posts** - Caption and accessibility translations for your posts Use the filters to find specific translations: * Search bar to find specific text * Dropdown filter by solution (Program, UGC, Activities, Tiers, etc.) * Filter for texts that need review *** ## Manual adjustments While translations happen automatically, you can adjust any translation manually. 1. Navigate to [Settings -> Translations](https://app.cevoid.com/settings/translations) 2. Click **Localize** on the language you want to edit 3. Find the text you want to change 4. Enter your translation 5. Click **Save** Dynamic values like `{pointsAmount}` and `{pointsName}` must be kept in your translations. These ensure correct data is displayed in your widgets. *** ## Translation exceptions Some branded content works better when kept consistent across all languages. Use translation exceptions to control whether tier names and points names are translated or kept in your primary language. Navigate to [Settings -> Translations](https://app.cevoid.com/settings/translations) to configure exceptions. | Setting | Options | | ---------------- | ----------------------------------------------- | | *Name of tiers* | Should be translated / Should not be translated | | *Name of points* | Should be translated / Should not be translated | For example, if your points are called "Stars" as part of your brand identity, you may want to keep that name across all markets rather than translating it to "Sterne" in German or "Stjärnor" in Swedish. Learn more about customizing your points name in [Points branding](/program/program-setup/points-branding). # Help Center Source: https://docs.cevoid.com/help-center/index Your brand engagement platform for ecommerce. Welcome to the Cevoid Help Center. Here you'll find everything you need to get the most out of your brand engagement platform. If you are building on Cevoid, use the [Developer Docs](/developer-docs). If you need public REST API details, use the [API Reference](/api-reference). *** ## Modules Cevoid is built around two powerful modules that work together or independently. Collect photos and videos from social media and directly from your customers, then showcase them in shoppable widgets across your website and marketing channels. Reward purchases, engagement, and customer contributions. Build a program with points, tiers, activities, competitions, and rewards that fit your brand. *** ## Localization Everything in Cevoid is localized automatically. Widgets display in the correct language, prices show in local currencies, and content adapts to each market - no manual work required. Connect your product catalog and configure markets for each localized version of your store. Manage translations for all consumer-facing copy. Write in your primary language and let Cevoid's AI handle the rest. *** ## Profiles Every customer interaction flows into unified profiles. Whether someone submits UGC, joins your rewards program, or makes a purchase, their activity is connected in one place. View and manage your customer profiles. Collect custom data like preferences, sizes, and interests. Group profiles dynamically based on behavior and attributes. *** ## More WCAG-compliant widgets with automatic alt text and video captions. Configure consent collection and legal policies for your markets. Organize posts and profiles with custom labels for filtering and automation. *** ## Integrations Cevoid offers integrations to your ecommerce and CRM platforms. For stores on other platforms, we offer a general implementation. Sync products, track purchases, and embed widgets. Trigger flows and sync program data. Sync profiles and program events. Collect tagged content and hashtag posts. Sync your brand's TikTok content. Sync products and track purchases. Sync catalogs via XML, CSV, or TSV feeds. Connect your own user system. *** ## Need help? Can't find what you're looking for? Click the chat icon in the corner to reach our support team. # Custom customer authentication for program widgets Source: https://docs.cevoid.com/integrations/custom-customer-authentication Implement custom authentication to connect your store's user system with Cevoid program widgets. Related articles: [Member access and login](/program/program-setup/member-access-login), [Member opt-in and enrollment](/program/program-setup/member-opt-in-enrollment), [On-site widgets](/program/on-site-widgets) Custom customer authentication allows you to authenticate users with your own system instead of using Shopify accounts or Cevoid email authentication. This is useful for headless setups or stores running on platforms other than Shopify. The implementation involves encrypting a payload with a key provided by Cevoid and attaching the result to your widget embed code. This implementation requires server-side code. The encryption key must never be exposed to the client or shared with anyone. *** ## How it works 1. You retrieve user information from your authenticated session 2. You create an encrypted digest on the server using the user's ID and email 3. You pass the digest and user info to the Cevoid widget div code 4. Cevoid verifies the digest and authenticates the user *** ## Set up custom customer authentication ### Step 1: Enable custom customer authentication 1. Navigate to [Settings -> Loyalty -> General](https://app.cevoid.com/settings/loyalty/general) 2. Under *Access and enrollment*, set **Authentication** to **Custom customer authentication** 3. Copy your **encryption key** and **tracking ID** from this page ### Step 2: Get your widget embed code 1. Navigate to [Rewards program -> On-site widgets](https://app.cevoid.com/program/widgets) 2. Select the widget you want to embed 3. Click **Embed** in the top right corner 4. Copy the div code The base embed code looks like this: ```html theme={"system"}
``` ### Step 3: Add user information to the embed code Add the following data attributes with your authenticated user's information: | Attribute | Required | Description | | ----------------- | -------- | ---------------------------- | | `data-user-email` | Yes | The user's email address | | `data-user-id` | Yes | The user's ID in your system | | `data-user-name` | No | The user's display name | ```html theme={"system"}
``` ### Step 4: Create the digest The digest authenticates the user and must be generated server-side. **Payload format:** `{{ USER_ID }},{{ EMAIL }}` For example, for a user with ID `1234` and email `viktor@cevoid.com`, the payload is: ``` 1234,viktor@cevoid.com ``` **Encryption method:** HMAC with SHA256 algorithm, signed with your encryption key. **Node.js example:** ```javascript theme={"system"} const crypto = require('crypto'); const encryptionKey = 'YOUR_ENCRYPTION_KEY'; const userId = '1234'; const email = 'viktor@cevoid.com'; const digest = crypto .createHmac('sha256', encryptionKey) .update(`${userId},${email}`) .digest('hex'); ``` ### Step 5: Add the digest to the embed code Add the generated digest as `data-digest`: ```html theme={"system"}
``` *** ## Complete example For a user with: * ID: `1234` * Email: `viktor@cevoid.com` * Name: `Viktor` The final embed code would look like: ```html theme={"system"}
``` # Instagram Source: https://docs.cevoid.com/integrations/instagram Connect your Instagram accounts to collect UGC, sync your feed, and schedule posts. Related articles: [Instagram feed sync](/ugc/collect/instagram-feed), [UGC from Instagram](/ugc/collect/ugc-from-instagram), [Social scheduling](/ugc/social-scheduling), [Post on Instagram activity](/program/activities/available-tasks#post-on-instagram) The Instagram integration connects your Instagram business accounts to Cevoid. Once connected, you can sync posts from your Instagram feed, collect user-generated content from mentions and tags, and schedule posts for automatic publishing. Navigate to [Settings -> Integrations -> Instagram](https://app.cevoid.com/settings/integrations/instagram) to manage your Instagram integration. *** ## What you can do with the Instagram integration | Feature | Description | | ---------------------------- | ----------------------------------------------------------------------------------- | | **Sync your Instagram feed** | Automatically import posts from your brand's Instagram feed to use on your website | | **Collect UGC** | Detect and collect posts where customers mention, tag, or use your tracked hashtags | | **Schedule posts** | Schedule and auto-publish reels, images, carousels, and stories to Instagram | *** ## Prerequisites Before connecting, ensure your Instagram account meets these requirements: | Requirement | Meta guide | | -------------------------------------- | ------------------------------------------------------------------------------------- | | Instagram business account | [Convert to business account](https://www.facebook.com/business/help/502981923235522) | | Connected to a Meta Business page | [Connect Instagram to a page](https://www.facebook.com/business/help/898752960195806) | | Admin rights on the Meta Business page | [Manage page roles](https://www.facebook.com/business/help/442345745885606) | *** ## Connect an Instagram account 1. Navigate to [Settings -> Integrations -> Instagram](https://app.cevoid.com/settings/integrations/instagram) 2. Click **Connect Instagram** A Facebook pop-up opens: 1. Click **Connect Instagram using Facebook** 2. Log in with your Facebook credentials (or click **Edit previous settings** if already logged in) Choose what to connect at each step: | Step | Recommended option | | ---------------------- | ----------------------------------------------------- | | **Pages** | *Opt in to all current and future Pages* | | **Meta Businesses** | *Opt in to all current and future Businesses* | | **Instagram accounts** | *Opt in to all current and future Instagram accounts* | Click **Continue** after each selection, then click **Save** and **Got it**. 1. Select the accounts you want to connect to your workspace 2. Click **Connect accounts** *** ## Connect additional accounts You can connect multiple Instagram accounts to the same workspace. This allows brands with multiple accounts to capture and reuse Instagram content in one place. To add more accounts, follow the same steps as above. The Facebook pop-up lets you authorize additional pages and accounts that weren't previously connected. # Klaviyo Source: https://docs.cevoid.com/integrations/klaviyo Sync profile data and events to Klaviyo, trigger email flows, and add UGC to your Klaviyo emails. Related articles: [Profile data & event sharing](/general/profiles/profile-data-event-sharing), [Program emails & triggers](/program/program-setup/program-emails-and-triggers), [Email widgets](/ugc/showcase/email-widgets) Cevoid's Klaviyo integration lets you sync profile data and events to Klaviyo, build email flows triggered by program activities, and showcase UGC in your Klaviyo emails. You can connect multiple Klaviyo accounts to the same workspace. Navigate to [Settings -> Integrations -> Klaviyo](https://app.cevoid.com/settings/integrations/klaviyo) to manage your Klaviyo integration. *** ## What you can do with the Klaviyo integration The Klaviyo integration enables three main use cases: **Sync profile data to Klaviyo** - Keep Klaviyo profiles updated with data collected in Cevoid, including program membership status, points balance, tier information, and custom profile properties. Use this data to build segments and personalize your emails. **Send events to Klaviyo** - Trigger email flows based on program activities like joining the program, completing challenges, earning tiers, and redeeming rewards. Each event includes relevant data you can use in your email content. **Add UGC to your emails** - Create email widgets that showcase user-generated content in your Klaviyo campaigns and flows. Learn more in [Email widgets](/ugc/showcase/email-widgets). *** ## Connect a Klaviyo account You can connect multiple Klaviyo accounts to your Cevoid workspace. Each connection is linked to a specific store in your workspace. 1. Navigate to [Settings -> Integrations -> Klaviyo](https://app.cevoid.com/settings/integrations/klaviyo) 2. Click **Add account** in the Connections section 3. Select the store you want to link this Klaviyo account to 4. You are redirected to Klaviyo to authorize the connection 5. Approve the requested permissions 6. You are redirected back to Cevoid Once connected, the account appears in your Connections list with a **Connected** status. *** ## Configure event sharing Events allow you to trigger email flows in Klaviyo based on activities in Cevoid. Events are configured globally and sync to all connected Klaviyo accounts. 1. Navigate to [Settings -> Integrations -> Klaviyo](https://app.cevoid.com/settings/integrations/klaviyo) 2. Click **Edit events** in the Events section 3. Toggle on the events you want to sync to Klaviyo 4. Click **Save** Events are sent to Klaviyo in real-time when they occur. Each event includes relevant data that you can use in your email content. For example, the *Cevoid: Reward Fulfilled* event includes reward details, and the *Cevoid: Tier Earned* event includes tier information and entry rewards connected to that tier. For a complete list of available events and their payloads, see [Profile data & event sharing](/general/profiles/profile-data-event-sharing). *** ## Configure profile data sharing Profile data keeps your Klaviyo profiles in sync with information collected in Cevoid. Profile data is configured globally and syncs to all connected Klaviyo accounts. 1. Navigate to [Settings -> Integrations -> Klaviyo](https://app.cevoid.com/settings/integrations/klaviyo) 2. Click **Edit fields** in the Profile Data section 3. Toggle on the profile data fields you want to sync to Klaviyo 4. Click **Save** Profile data syncs automatically when it is collected or updated in Cevoid. The data appears as custom properties on the corresponding Klaviyo profile. For a complete list of available profile data fields, see [Profile data & event sharing](/general/profiles/profile-data-event-sharing). Use the **Test Profile** button in the Profile Data modal to preview how profile data will appear in Klaviyo. *** ## Sync existing profiles to Klaviyo When you first enable profile data sharing or add new fields, existing profiles in Cevoid are not automatically synced. Use the manual sync to push existing profile data to Klaviyo. 1. Navigate to [Settings -> Integrations -> Klaviyo](https://app.cevoid.com/settings/integrations/klaviyo) 2. Click **Sync profiles** in the Profile Data section 3. Select the Klaviyo account to sync with 4. Optional: Toggle on *Sync specific segments* to limit the sync to specific profile segments 5. Click **Sync profiles** Profiles that don't exist in Klaviyo will be created automatically if you have enabled the *Create profile* behavior in General Settings. *** ## General settings General settings control global Klaviyo behavior for all connected accounts. ### Profile sync behavior This setting determines what happens when Cevoid tries to sync data to a profile that doesn't exist in Klaviyo. | Option | Description | | ------------------------ | --------------------------------------------------- | | **Create profile** | Cevoid creates the profile in Klaviyo automatically | | **Don't create profile** | Cevoid skips profiles that don't exist in Klaviyo | By default, *Profile sync behavior* is set to **Create profile**, so new profiles are automatically added to Klaviyo when their data is synced. *** ## Connection settings Each connected Klaviyo account has individual settings that control how profiles are handled for that specific connection. To access connection settings: 1. Navigate to [Settings -> Integrations -> Klaviyo](https://app.cevoid.com/settings/integrations/klaviyo) 2. Click on a connected account in the Connections section ### Available settings | Setting | Description | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | *Store* | The store in your workspace that this Klaviyo account is linked to | | *Add new profiles to list* | Select a Klaviyo list where new profiles should be added | | *Forward email marketing opt-in event to Klaviyo* | Forward marketing consent opt-in collected through Cevoid widgets to Klaviyo. You can select which Klaviyo list(s) should receive opt-in events. | | *Forward email marketing opt-out event to Klaviyo* | Forward marketing consent opt-out from the program through Cevoid widgets to Klaviyo | ### Marketing consent forwarding When enabled, marketing consent collected through Cevoid widgets is forwarded to Klaviyo. This applies to consent collected during program opt-in or through other Cevoid widgets where marketing consent is requested. *** ## Disconnect a Klaviyo account 1. Navigate to [Settings -> Integrations -> Klaviyo](https://app.cevoid.com/settings/integrations/klaviyo) 2. Click on the connected account you want to remove 3. Click **Disable** Disconnecting stops all data syncing and event sharing with that Klaviyo account. Historical data that was already synced remains in Klaviyo. *** ## Build email flows in Klaviyo Use Cevoid events to trigger email flows in Klaviyo. Each event includes data you can use to personalize your emails. ### Example: New tier reached This flow triggers when a member reaches a new tier. 1. In Klaviyo, create a new flow 2. Select **Metric** as the trigger 3. Choose **Cevoid: Tier Earned** 4. Click **Save** 5. Add your email content The event includes tier name, milestone, and entry rewards connected to that tier. Use these values to personalize the email with the member's new tier and rewards. ### Example: Reward fulfilled This flow triggers when a member's reward is fulfilled. 1. In Klaviyo, create a new flow 2. Select **Metric** as the trigger 3. Choose **Cevoid: Reward Fulfilled** 4. Click **Save** 5. Add your email content The event includes reward details like name, description, and redemption instructions. ### Example: Challenge available This flow triggers when a new challenge becomes available to a member. 1. In Klaviyo, create a new flow 2. Select **Metric** as the trigger 3. Choose **Cevoid: Challenge Available** 4. Click **Save** 5. Add your email content The event includes the challenge title and description. *** ## Build segments in Klaviyo Use Cevoid profile data to build segments in Klaviyo for targeted campaigns. ### Example: All rewards program members Target all active members of your rewards program. 1. In Klaviyo, create a new segment 2. Add condition: **Properties about someone** 3. Set property: **Cevoid: Program Member** 4. Set value: **is true** 5. Click **Create segment** ### Example: Members in a specific tier Target members who have reached a specific tier. 1. In Klaviyo, create a new segment 2. Add condition: **Properties about someone** 3. Set property: **Cevoid: Tier Name** 4. Set value: **equals \[your tier name]** 5. Click **Create segment** ### Example: Members who completed a challenge Target members who have completed any challenge. 1. In Klaviyo, create a new segment 2. Add condition: **What someone has done (or not done)** 3. Set metric: **Cevoid: Challenge Completed** 4. Set value: **at least once over all time** 5. Click **Create segment** To target members who completed a specific challenge, add a filter for the challenge title or shortId. *** ## UGC email widgets for Klaviyo Showcase user-generated content in your Klaviyo emails with Cevoid's email widgets. You can create dynamic widgets that automatically update with your latest approved posts, or static widgets with hand-picked content. Klaviyo supports the following email widget types: * **Static email widget** - Display specific posts you manually select * **Dynamic email widget** - Automatically update with posts matching your filters * **Instagram Feed email widget** - Show your latest approved Instagram feed posts * **Abandoned Cart email widget** - Display posts featuring products left in the cart * **Post-Purchase email widget** - Show posts featuring purchased products For step-by-step instructions on creating and embedding email widgets, see [Email widgets](/ugc/showcase/email-widgets). *** ## How profiles are synced with multiple Klaviyo accounts When you have multiple Klaviyo accounts connected to your workspace, Cevoid routes profiles based on their market to avoid multiple accounts sending emails to the same person. **One Klaviyo account connected:** Profiles sync to that account regardless of which market they belong to. **Multiple Klaviyo accounts connected:** Profiles only sync to the Klaviyo account linked to their market. This prevents duplicate emails from different regional accounts. In both cases, profiles with an email that already exists in Klaviyo sync automatically. Profiles with an email that doesn't exist in Klaviyo only sync if you've set *Profile sync behavior* to **Create profile**. *** ## Klaviyo scopes When you connect a Klaviyo account, Cevoid requests the following permissions: | Scope | Used for | | ------------------------------------------------------ | ----------------------------------------- | | accounts:read | All Klaviyo-related features | | metrics:read, metrics:write, events:read, events:write | Sending events to Klaviyo for email flows | | profiles:read, profiles:write | Syncing profile data to Klaviyo | | lists:read, lists:write | Adding profiles to Klaviyo lists | | subscriptions:write | Forwarding marketing consent to Klaviyo | # Product feeds Source: https://docs.cevoid.com/integrations/product-feeds Sync your product catalog to Cevoid using product feeds. Related articles: [Products & Markets](/general/products-markets), [UGC introduction](/ugc/introduction), [Galleries](/ugc/showcase/galleries) Product feeds sync your product catalog with Cevoid, enabling product tags on posts and product-based galleries. Use product feeds when you're not using Shopify or WooCommerce, or when you need custom catalog data. Navigate to [Settings -> Products & Markets](https://app.cevoid.com/settings/products-and-markets) to configure your feeds. *** ## Add a product feed 1. Navigate to [Settings -> Products & Markets](https://app.cevoid.com/settings/products-and-markets) 2. Edit an existing market or create a new one 3. Scroll to the Product feed section 4. Click **Add product feed** 5. Enter the URL to your product feed 6. Select the file format (XML, CSV, or TSV) 7. If password-protected, click **Authentication** and enter credentials 8. Click **Connect feed** 9. Map each field to the corresponding value in your feed 10. Click **Create feed** *** ## Field mapping Once connected, a preview of your feed displays. Map your feed fields to Cevoid's values. | Field | Required | Description | Used for | | | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------- | | *ID* | ✓ | Unique identifier for each product variant | Connects products across markets so you only tag once | | | *Product title* | ✓ | The product name | Displayed in product tags | | | *Link* | ✓ | URL to the product page | Where visitors go when clicking a product tag | | | *Product price* | ✓ | Price. With or without currency symbol; symbol is removed at import. | Displayed in product tags | | | *Image link* | ✓ | Primary product image | Displayed in product tags | | | *Item group ID* | | Groups product variants together | Product tagging and product page gallery fallback | | | *Additional image link* | | Secondary product image | Shown on hover over product tag | | | *Sale price* | | Discounted price if on sale | Displayed alongside regular price | | | *Availability* | | Stock status | Hide out-of-stock products | | | *Category* | | Hierarchical categories
Supported seperators: \`, / | > \< →\` | Tagging filter, Library filter, category page galleries | | *Collection(s)* | | The collections the product belongs to.
Can be send as one tag, or seperate once for grouped collections | Tagging filter, Library filter, collection page galleries | | | *Variant options* | | Options like color and size
One tag per variant option. | Variant selection when tagging, product page gallery fallback | | Item group ID is strongly recommended. It groups product variants together for better tagging and fallback behavior. If you don't provide Item group ID, Cevoid analyzes URL paths to create groupings automatically ## Product feed example ```javascript theme={"system"} {/* Required fields */} 1001-BLK-M Classic Cotton T-Shirt https://cevoid.com/product/classic-cotton-t-shirt 29.99 https://cdncevoid.com/image/classic-tee-black-front.jpg {/* Optional fields */} 1001 https://cdncevoid.com/image/classic-tee-black-lifestyle.jpg 19.99 in_stock Apparel > Tops > T-Shirts {/* Collections (Optional) */} Women, Unisex Casual, Streetwear, Minimalist, Everyday {/* Variant options (Optional) */} M Black ``` *** ## FAQ **What format should feeds be in?** Google Shopping feed schema is most common, but we support custom field names that you map during setup. **What file formats are supported?** XML, CSV, or TSV. **Can we have multiple feeds per market?** Yes. Add multiple feeds if your catalog is split across files. Usually one is enough. **What if we modify our feeds?** All fields except product ID can be remapped freely. Changes apply after the next product sync. Product tags are connected to the product ID. Contact Cevoid support before remapping the ID field. # Shopify Source: https://docs.cevoid.com/integrations/shopify Connect your Shopify stores to sync products, track purchases, share profile data, and add widgets to your storefront. Related articles: [Profile data & event sharing](/general/profiles/profile-data-event-sharing), [Products & Markets](/general/products-markets), [Galleries](/ugc/showcase/galleries), [On-site widgets](/program/on-site-widgets), [Purchases settings](/program/program-setup/purchases) Cevoid's Shopify integration connects your store with both the UGC module and Rewards program module. Sync your product catalog for product tags, track purchases for your rewards program, share profile data back to Shopify, and add widgets to your storefront without writing code. The integration works with both separate Shopify stores and Shopify Markets, allowing you to localize all consumer-facing solutions through [Markets](/general/products-markets). *** ## Connect a Shopify store There are two ways to connect a Shopify store to your Cevoid workspace. ### Install a Cevoid Shopify app We recommend installing one of our Shopify apps to create your workspace and connect your first store. 1. Find Cevoid's [UGC app](https://apps.shopify.com/cevoid) or [Rewards program app](https://apps.shopify.com/cevoid-loyalty) on the Shopify App Store 2. Click **Install** 3. Approve the requested permissions Once your workspace is set up, you can install the other Cevoid app on the same store, and it will automatically connect to the same workspace. ### Connect an additional store To connect additional Shopify stores to an existing workspace: 1. Navigate to [Settings -> Products and markets](https://app.cevoid.com/settings/products-and-markets) or [Settings -> Integrations -> Shopify](https://app.cevoid.com/settings/integrations/shopify) 2. Click **Add store** 3. Enter your Shopify store domain (e.g., yourstore.myshopify.com) 4. Click **Connect store** 5. You are redirected to Shopify to authorize the connection 6. Approve the requested permissions 7. You are redirected back to Cevoid Connected stores appear in the Stores section on the [Shopify integration page](https://app.cevoid.com/settings/integrations/shopify). If you connect multiple separate Shopify stores, change the *Global product identifier* to **Barcode** or **SKU** in [Settings -> Products and markets](https://app.cevoid.com/settings/products-and-markets). This ensures products sync correctly across stores, since product IDs differ between separate Shopify stores. ### Add markets from Shopify Markets If your Shopify store uses Shopify Markets, you can add them as markets in Cevoid. 1. Navigate to [Settings -> Products and markets](https://app.cevoid.com/settings/products-and-markets) 2. Click **New market** 3. Select the Shopify store you want to add markets from 4. Select the Shopify Markets you want to add 5. Click **Add market(s)** 6. Adjust each market's settings if needed For more details on market configuration, see [Products & Markets](/general/products-markets). *** ## UGC module Install the [Cevoid UGC app](https://apps.shopify.com/cevoid) to add UGC widgets to your Shopify store. Learn more about [UGC with Cevoid](/ugc/introduction). ### Product catalog sync Your product catalog syncs automatically from your connected Shopify stores. Products are available immediately for tagging UGC posts and displaying product information in widgets. You only need to tag a product once, regardless of how many markets you have connected. The product tag automatically displays the correct price, currency, and link for each market. ### Add UGC widgets to your Shopify store The easiest way to add UGC widgets to your Shopify store is with Cevoid's prebuilt theme sections. No code required. 1. Navigate to [UGC -> On-site widgets](https://app.cevoid.com/ugc/on-site-widgets) and select your gallery 2. Click **Embed gallery** 3. Copy the Gallery ID 4. In Shopify, open your theme editor 5. Navigate to the page where you want the gallery 6. Click **Add section** and search for "Cevoid gallery" 7. Paste the Gallery ID 8. Click **Save** For product page galleries, use the "Product page gallery" section. For collection page galleries, use the "Collection page gallery" section. These ensure content updates dynamically for each product or collection. You can also add galleries using custom Liquid or HTML sections. For detailed instructions on all embedding options, see [Galleries](/ugc/showcase/galleries). ### Conversion tracking for UGC analytics Enable conversion tracking to see additional metrics like conversion rate on your UGC posts. 1. Navigate to [Analytics](https://app.cevoid.com/analytics) 2. Click **Implementation instructions** 3. Click **Enable** for each Shopify store you want to track 4. Copy the cookie information and add it to your cookie policy 5. Select your reporting currency 6. Click **Enable** Cevoid's UGC analytics don't use cookies except when conversion tracking is enabled. ### Group non-variant products Most brands add variants directly to products in Shopify (e.g., a t-shirt with size and color options). These variants automatically share UGC across the product page gallery. Some brands set up separate products in Shopify for each variant instead (e.g., the black t-shirt and white t-shirt are separate products). For these setups, you can group the products so they share UGC content. 1. In Shopify, navigate to the product 2. Add a tag prefixed with `cevoid:` followed by a unique identifier (e.g., `cevoid:running-shorts`) 3. Add the same tag to all other products you want to group together Products with the same `cevoid:` tag will share images and videos in the product page gallery. Products can have multiple `cevoid:` tags if needed. *** ## Rewards program module Install the [Cevoid Rewards program app](https://apps.shopify.com/cevoid-loyalty) to track purchases and add program widgets to your Shopify store. Learn more about [Rewards programs with Cevoid](/program/introduction). ### Purchase tracking Cevoid automatically tracks orders from your connected Shopify stores. Tracked orders can be used to reward purchases with points and progress members through tier milestones. Configure which orders to track, what parts of an order count, and when orders are processed in [Purchases settings](/program/program-setup/purchases). ### Discount code rewards Discount code rewards are configured in Cevoid and match Shopify's discount code settings. When a member redeems a discount code reward, Cevoid automatically creates the discount code in your Shopify store. The discount amount displays in the correct currency for each market. This works with both Shopify Markets and separate Shopify stores. ### Add rewards program widgets to your Shopify store Cevoid's Shopify app for Rewards programs lets you add program widgets to your store using prebuilt theme sections. 1. In Shopify, open your theme editor 2. Navigate to the page where you want the widget 3. Click **Add section** 4. Select the **Apps** tab 5. Search for "Cevoid" and select the widget you want to add The design, copy, and layout of each widget is configured in Cevoid. See [On-site widgets](/program/on-site-widgets) for details on available widgets and customization options. All rewards program widgets work with both Shopify legacy customer accounts and new customer accounts. However, only selected widgets are available for customer account pages when using new accounts. ### Shopify customer accounts for authentication When you connect a Shopify store, Cevoid automatically uses Shopify customer accounts for authentication. Members log in to your rewards program widgets using their existing Shopify store account, providing a native experience where members use the same login they use for the rest of your store. Shopify customer accounts work with both legacy customer accounts and new customer accounts. | Area | Legacy accounts | New accounts | | ---------------- | ------------------------------------ | ----------------------------------- | | Login method | Email and password | One-time code sent to email | | Account creation | Customers actively create an account | Customers access profile with email | For other authentication options, see [Member access and login](/program/program-setup/member-access-login). ### Opt-in rules and Shopify account types Your opt-in rules determine when customers become members of your rewards program. Some opt-in rules are only available with legacy customer accounts. | Opt-in rule | Legacy accounts | New accounts | | -------------------------------- | --------------- | ------------- | | Store account and program action | ✓ | Not available | | Store account | ✓ | Not available | | All customers | ✓ | ✓ | | Widget opt-in | ✓ | ✓ | | Invite only | ✓ | ✓ | For details on each opt-in rule, see [Member opt-in and enrollment](/program/program-setup/member-opt-in-enrollment). *** ## Widget localization All Cevoid widgets automatically display in the correct language, currency, and prices based on the market. For Shopify stores using market-specific URLs, widgets detect the market from the URL. For stores without market-specific URLs, Cevoid's Shopify sections detect the correct market automatically. Purchase incentives show the correct points-per-currency rate, and discount code rewards display amounts in the local currency. This works with both Shopify Markets and separate Shopify stores. You need markets configured in Cevoid for localization to work. See [Products & Markets](/general/products-markets) for setup instructions. *** ## Configure profile data sharing Share profile data from Cevoid to your Shopify customers. This allows you to personalize your storefront or build customer segments in Shopify based on program membership, tier status, points balance, and more. Profile data is configured globally and syncs to all connected Shopify stores. Profiles will only be synced with a customer that exists in your store. If the profile's email is not associated with a customer, it will not be synced. ### Share data as metafields Metafields store profile data as structured customer metafields in Shopify. 1. Navigate to [Settings -> Integrations -> Shopify](https://app.cevoid.com/settings/integrations/shopify) 2. Click **Edit fields** in the Metafields row 3. Toggle on the fields you want to sync to Shopify 4. Click **Save** ### Share data as tags Tags add profile data as customer tags in Shopify. Each enabled field creates a tag on the customer. 1. Navigate to [Settings -> Integrations -> Shopify](https://app.cevoid.com/settings/integrations/shopify) 2. Click **Edit tags** in the Tags row 3. Toggle on the tags you want to sync to Shopify 4. Click **Save** For a complete list of available profile data fields, see [Profile data & event sharing](/general/profiles/profile-data-event-sharing). *** ## Sync existing profiles to Shopify When you first enable profile data sharing or add new fields, existing profiles in Cevoid are not automatically synced. Use the manual sync to push existing profile data to Shopify. 1. Navigate to [Settings -> Integrations -> Shopify](https://app.cevoid.com/settings/integrations/shopify) 2. Click **Sync profiles** 3. Select the Shopify store to sync with 4. Optional: Toggle on *Sync specific segments* to limit the sync to specific profile segments 5. Click **Sync profiles** Only profiles linked to existing Shopify customers will be synced. *** ## How profiles are synced with multiple Shopify stores When you have multiple Shopify stores connected to your workspace, Cevoid routes profiles based on their market. **One Shopify store connected:** Profiles sync to that store regardless of which market they belong to. **Multiple Shopify stores connected:** Profiles only sync to the Shopify store linked to their market. This ensures customer data stays with the appropriate regional store. In both cases, profiles only sync if their email matches an existing Shopify customer. Learn more about how profiles are mapped to markets in [Profile data & event sharing](/general/profiles/profile-data-event-sharing#multiple-crm-accounts-or-stores). # TikTok Source: https://docs.cevoid.com/integrations/tiktok Connect your TikTok accounts to sync your feed content to Cevoid. Related articles: [TikTok feed sync](/ugc/collect/tiktok-feed) The TikTok integration connects your TikTok accounts to Cevoid. Once connected, you can sync posts from your TikTok feed to use as part of your UGC strategy. Navigate to [Settings -> Integrations -> TikTok](https://app.cevoid.com/settings/integrations/tiktok) to manage your TikTok integration. *** ## Connect a TikTok account Log in to the TikTok account you want to connect on [TikTok.com](https://www.tiktok.com/) before starting. 1. Navigate to [Settings -> Integrations -> TikTok](https://app.cevoid.com/settings/integrations/tiktok) 2. Click **Enable** 3. You are redirected to TikTok 4. Approve the connection *** ## Connect additional accounts You can connect multiple TikTok accounts to the same workspace. This allows brands with multiple accounts to capture and reuse TikTok content in one place. Log in to the TikTok account you want to connect on [TikTok.com](https://www.tiktok.com/) before starting. 1. Navigate to [Settings -> Integrations -> TikTok](https://app.cevoid.com/settings/integrations/tiktok) 2. Click **Add connection** 3. You are redirected to TikTok 4. Approve the connection # Voyado Source: https://docs.cevoid.com/integrations/voyado Sync profile data and events to Voyado, trigger automations, and add UGC to your Voyado emails. Related articles: [Profile data & event sharing](/general/profiles/profile-data-event-sharing), [Email widgets](/ugc/showcase/email-widgets) Cevoid's Voyado integration lets you sync profile data and events to Voyado, trigger automations based on program activities, and showcase UGC in your Voyado emails. You can also use Voyado's points system as your points provider in Cevoid. Navigate to [Settings -> Integrations -> Voyado](https://app.cevoid.com/settings/integrations/voyado) to manage your Voyado integration. *** ## What you can do with the Voyado integration The Voyado integration enables four main use cases: **Sync profile data to Voyado** - Keep Voyado contacts updated with data collected in Cevoid, including program membership status, points balance, tier information, and custom profile properties. Use this data to build segments and personalize your communications. **Send events to Voyado** - Trigger automations based on program activities like joining the program, completing challenges, earning tiers, and redeeming rewards. Events are sent as contact interactions and include relevant data you can use in your automations. **Add UGC to your emails** - Create email widgets that showcase user-generated content in your Voyado campaigns. Learn more in [Email widgets](/ugc/showcase/email-widgets). **Use Voyado as points provider** - Use your existing Voyado loyalty points instead of Cevoid's points system, allowing you to combine Cevoid's engagement features with your Voyado loyalty program. *** ## Connect a Voyado account 1. Navigate to [Settings -> Integrations -> Voyado](https://app.cevoid.com/settings/integrations/voyado) 2. Click **Enable** 3. Enter your Voyado API credentials (API key and client name) 4. Click **Connect** Once connected, the integration shows an **Enabled** status with your connected Voyado instance. *** ## Configure event sharing Events allow you to trigger automations in Voyado based on activities in Cevoid. Events are sent as contact interactions. 1. Navigate to [Settings -> Integrations -> Voyado](https://app.cevoid.com/settings/integrations/voyado) 2. Click **Edit events** in the Events section 3. Toggle on the events you want to sync to Voyado 4. Click **Save** Events are sent to Voyado in real-time when they occur. Each event includes relevant data that you can use in your automation content. For example, the *Cevoid: Reward Fulfilled* event includes reward details, and the *Cevoid: Tier Earned* event includes tier information. For a complete list of available events and their payloads, see [Profile data & event sharing](/general/profiles/profile-data-event-sharing). ### Send a test event You can send a test event to verify your setup. Sending a test event triggers the event on a test profile and makes it available in Voyado. 1. Navigate to [Settings -> Integrations -> Voyado](https://app.cevoid.com/settings/integrations/voyado) 2. In the Events section, click the play icon next to an event 3. Click **Send and verify event** *** ## Configure profile data sharing Profile data keeps your Voyado contacts in sync with information collected in Cevoid. 1. Navigate to [Settings -> Integrations -> Voyado](https://app.cevoid.com/settings/integrations/voyado) 2. Click **Edit fields** in the Profile Data section 3. Toggle on the profile data fields you want to sync to Voyado 4. Click **Save** Profile data syncs automatically when it is collected or updated in Cevoid. The data appears as custom properties on the corresponding Voyado contact. For a complete list of available profile data fields, see [Profile data & event sharing](/general/profiles/profile-data-event-sharing). ### Send test profile data You can send test profile data to preview how it appears in Voyado. This creates a test profile with all activated fields. 1. Navigate to [Settings -> Integrations -> Voyado](https://app.cevoid.com/settings/integrations/voyado) 2. In the Profile Data section, click the play icon 3. Click **Create test profile** *** ## Sync existing profiles to Voyado When you first enable profile data sharing or add new fields, existing profiles in Cevoid are not automatically synced. Use the manual sync to push existing profile data to Voyado. 1. Navigate to [Settings -> Integrations -> Voyado](https://app.cevoid.com/settings/integrations/voyado) 2. Click **Sync all profiles** in the Profile Data section 3. Optional: Toggle on *Sync specific segments* to limit the sync to specific profile segments 4. Click **Sync profiles** Profiles that don't exist in Voyado will be created automatically if you have enabled the *Create profile* behavior in General Settings. *** ## General settings General settings control global Voyado behavior. ### Profile sync behavior This setting determines what happens when Cevoid tries to sync data to a profile that doesn't exist in Voyado. | Option | Description | | ------------------------ | -------------------------------------------------- | | **Create profile** | Cevoid creates the contact in Voyado automatically | | **Don't create profile** | Cevoid skips profiles that don't exist in Voyado | *** ## UGC email widgets for Voyado Showcase user-generated content in your Voyado emails with Cevoid's email widgets. Contact your customer success manager at Voyado to enable their email module for UGC email widgets from Cevoid. Voyado email widgets display a single row of four posts. You can configure what happens when a reader clicks a post and include the following information with each post: * Username (the creator of the post) * Product name (the name of the first product tagged in the post) * Product price (the price of the first product tagged in the post) Voyado supports the following email widget types: * **Dynamic email widget** - Automatically update with posts matching your filters, or hand-pick specific posts * **Instagram Feed email widget** - Show your latest approved Instagram feed posts For step-by-step instructions on creating email widgets, see [Email widgets](/ugc/showcase/email-widgets). ### Add an email widget to a Voyado email 1. Navigate to [UGC -> Email widgets](https://app.cevoid.com/email-widgets) 2. Select the email widget you created 3. Click **Embed widget** 4. Copy the email widget ID 5. In Voyado, open the email you want to add the widget to 6. Add the Cevoid module 7. Paste the email widget ID 8. Enter the country code (e.g., SE, NO, DK) - this is used to fetch localized product names and prices 9. Click **Save** *** ## Use Voyado as points provider You can use your existing Voyado loyalty points instead of Cevoid's points system. This allows you to combine Cevoid's engagement features (activities, challenges, widgets) with your established Voyado loyalty program. When a points reward is fulfilled in Cevoid, the points are distributed through Voyado's system to the member. 1. Navigate to [Settings -> Loyalty -> Points](https://app.cevoid.com/settings/loyalty/points) 2. In the *Points provider* setting, select **Voyado** 3. Click **Save changes** *** ## Disconnect Voyado 1. Navigate to [Settings -> Integrations -> Voyado](https://app.cevoid.com/settings/integrations/voyado) 2. Click **Disable** Disconnecting stops all data syncing and event sharing with Voyado. Historical data that was already synced remains in Voyado. # Webhooks via Flows Source: https://docs.cevoid.com/integrations/webhooks Send signed Cevoid events to your HTTPS endpoint from a Flow. Webhooks let a Flow notify your own service when something happens in Cevoid — an order is fulfilled, a review is submitted. Your service receives a signed `POST` with the order, profile, or review the event concerns, so you can act on it without polling for changes. Every request is signed, so you can verify it came from Cevoid. Requests are fixed `POST` calls with a JSON body; custom methods, custom authorization headers, and inbound webhooks are not supported. ## Prerequisites * You can access *Settings* and *Flows* in your Cevoid workspace. * You have a public HTTPS receiver that accepts `POST` requests, preserves the exact raw request body for signature verification, does not redirect, and returns a `2xx` response after accepting an event. ## Set up a webhook 1. Go to *Settings* → *Integrations* → *Cevoid API*. 2. Create a webhook destination. Result: Cevoid shows the signing secret once — copy it now and store it securely. 3. Go to *Settings* → *Flows* and create a Flow. 4. ***Choose*** `order.fulfilled`, `order.delivered`, `product-review.submitted`, or `company-review.submitted` as the trigger. 5. Add a webhook action and choose your destination. 6. Publish the Flow. Result: matching events start being delivered. You can also create the Flow directly from a destination. ## Request contract Cevoid sends an HTTPS `POST` with `content-type: application/json` and these [Standard Webhooks ](https://www.standardwebhooks.com/) headers: * `webhook-id`: stable public event ID; retries keep the same value * `webhook-timestamp`: Unix seconds for this attempt * `webhook-signature`: one or more `v1,` signatures Every event uses the same envelope. `type` tells you what happened, `data` holds the resources it concerns, and `origin.flow` names the Flow that sent it — useful when several Flows point at one destination. ```json theme={"system"} { "version": 1, "id": "d8177c1d-39da-4c4d-93cd-5964043735e4", "type": "order.fulfilled", "created_at": "2026-08-03T12:00:00.000Z", "data": { "order": { "id": "ord_7k2m4n8p", "order_number": "#1043", "currency": "SEK" }, "profile": { "id": "prf_c4n8x2q1", "name": "Astrid Lindqvist" } }, "origin": { "flow": { "id": "wfl_3p9v6d2s", "name": "Post-purchase review request" } } } ``` Test sends are signed and delivered the same way, with `type: "cevoid.test"`. ## Verify the exact raw body Verify the signature before parsing JSON. Build the signed content as: ```text theme={"system"} webhook-id + "." + webhook-timestamp + "." + exact_raw_request_body ``` Decode the base64 value after `whsec_`, calculate HMAC-SHA256, encode the digest as base64, and compare it in constant time with any `v1` signature in `webhook-signature`. Reject stale timestamps according to your replay-risk policy. During secret rotation, accept a match from either current secret while both signatures are present. ### Node.js ```js theme={"system"} import { createHmac, timingSafeEqual } from 'node:crypto' export function verifyCevoidWebhook({ rawBody, headers, secret }) { const id = headers['webhook-id'] const timestamp = headers['webhook-timestamp'] const signatureHeader = headers['webhook-signature'] if (typeof signatureHeader !== 'string') return false const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64') const expected = createHmac('sha256', key) .update(`${id}.${timestamp}.${rawBody}`, 'utf8') .digest() return signatureHeader.split(' ').some((entry) => { const [version, encoded] = entry.split(',', 2) if (version !== 'v1' || !encoded) return false const received = Buffer.from(encoded, 'base64') return received.length === expected.length && timingSafeEqual(received, expected) }) } ``` Pass `rawBody` directly from your framework's raw-body middleware. Do not use `JSON.stringify(req.body)`. ### Python ```python theme={"system"} import base64 import hashlib import hmac def verify_cevoid_webhook(raw_body: bytes, headers: dict[str, str], secret: str) -> bool: webhook_id = headers["webhook-id"] timestamp = headers["webhook-timestamp"] key = base64.b64decode(secret.removeprefix("whsec_"), validate=True) signed = webhook_id.encode() + b"." + timestamp.encode() + b"." + raw_body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() signature_header = headers.get("webhook-signature") if not signature_header: return False for entry in signature_header.split(" "): version, separator, signature = entry.partition(",") if version == "v1" and separator and hmac.compare_digest(signature, expected): return True return False ``` ### HMAC test vector This fixture is derived from the automated signing contract: ```text theme={"system"} secret: whsec_MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY= webhook-id: d8177c1d-39da-4c4d-93cd-5964043735e4 webhook-timestamp: 1785758400 raw body: {"created_at":"2026-08-03T12:00:00.000Z","data":{"message":"Test delivery from Cevoid"},"id":"d8177c1d-39da-4c4d-93cd-5964043735e4","type":"cevoid.test","version":1} webhook-signature: v1,hcbQFW+SLYnH9b62UxCSDnPyZW1rVaGPcA52jb9LBI0= ``` ## Respond and deduplicate * Return any `2xx` response once you have durably accepted the event. Result: Cevoid stops retrying it. * Store `webhook-id` and skip an ID you have already processed. Result: a retry after a lost response cannot create a duplicate on your side. * Sequence your own state from `created_at` or from the resource in `data`, not from arrival order. Events for the same order or profile can arrive in any sequence. * Do not redirect. Cevoid sends every request to the URL you configured. ### Retries Cevoid retries `408`, `425`, `429`, and `5xx` responses with a widening delay, over roughly a day. A `Retry-After` header is honoured when it asks for longer. Other `3xx` and `4xx` responses stop the delivery. Fix your receiver, then retry it from the delivery log. ### URL requirements Destination URLs must use HTTPS and resolve to a public address. They cannot contain credentials, fragments, or query strings. ## Test, retry, and replay * **Send test** sends a real signed `cevoid.test` request so you can check your receiver end to end. * **Retry** sends the same event again, with the same `webhook-id` and the same body. Use it after fixing your receiver. * **Replay** sends the same event data as a **new** event, with a new `webhook-id`, to your destination's current URL. Because the ID is new, your deduplication will not filter it. Each destination has a delivery log showing every attempt, the response status, and a preview of the response body. ## Troubleshooting * **No request arrives:** confirm the destination and the Flow are active, then check the delivery log. * **Signature mismatch:** verify against the exact raw bytes, not parsed JSON, and remove `whsec_` before base64 decoding. * **Repeated events:** deduplicate on `webhook-id`. * **Redirect or network error:** point the destination at the final public HTTPS URL. Redirects and private addresses are blocked. * **Delivery stopped retrying:** fix the reason shown in the delivery log, then retry it. * **Secret was lost:** rotate it. Accept both signatures during the overlap, deploy the new secret, then finish rotation. # WooCommerce Source: https://docs.cevoid.com/integrations/woocommerce Connect your WooCommerce store to sync products and track purchases. Related articles: [Products & Markets](/general/products-markets), [UGC introduction](/ugc/introduction), [Purchases](/program/program-setup/purchases) The WooCommerce integration connects your store to Cevoid, enabling: * **Product catalog sync** - Tag posts with products from your WooCommerce catalog * **Purchase tracking** - Track and reward purchases as part of your rewards program Navigate to [Settings -> Products & Markets](https://app.cevoid.com/settings/products-and-markets) to connect your store. *** ## Connect WooCommerce 1. Navigate to [Settings -> Products & Markets](https://app.cevoid.com/settings/products-and-markets) 2. Click **Connect WooCommerce** 3. Enter your store's WooCommerce domain 4. Click **Connect store** 5. On the WooCommerce authentication page, click **Approve** 6. You're redirected back to Cevoid and the connection is complete WooCommerce is selected when you create your workspace. Contact support if you need to switch from another integration. *** ## Required permissions The integration requests the following access: | Access | Used for | | ----------------------------- | ------------------------------------- | | View products | Product tags for UGC posts | | View orders and sales reports | Purchase tracking for rewards program | | View customers | Member identification for rewards | | View coupons | Discount code reward validation | *** ## Embed widgets For instructions on adding Cevoid widgets to your WooCommerce store, see [Galleries](../ugc/showcase/galleries) and [Cards](../ugc/showcase/cards). # Available tasks Source: https://docs.cevoid.com/program/activities/available-tasks Task types you can use in challenges and single-task activities. Related articles: [Activities overview](/program/activities/overview), [Challenges](/program/activities/challenges), [Single-task activities](/program/activities/single-task-activities) Tasks are the building blocks of your activities. Each task defines what members need to do to complete an activity or progress through a challenge. Some tasks are available for both challenges and single-task activities, while others are specific to one type. *** ## Content Collect photos, videos, and Instagram posts from members. | Task | Description | Challenges | Single-task activities | | --------------------- | ----------------------------------------------------- | :--------: | :--------------------: | | **Upload content** | Collect photos and videos, routed to your UGC library | ✓ | ✓ | | **Post on Instagram** | Ask members to post on Instagram, verified by Cevoid | ✓ | ✓ | ### Upload content Collect photos and videos from members. Submitted content can automatically be routed to your UGC library. **Available in:** Challenges, Single-task activities **How it works** 1. Member starts task 2. Member uploads content based on your requirements (see settings) 3. Member clicks continue 4. Task is completed 5. Content is saved to the submission and added to your UGC library (if enabled) **Task specific settings** | Setting | Required | Description | | ---------------------------------------- | :------: | ------------------------------------------------------------------------------------------------------ | | *Allowed media types* | ✓ | Choose what members can upload: images only, videos only, or any of them | | *Select content destination* | ✓ | Choose where submitted content is stored: Keep content in the submission, or Send content to the inbox | | *Min number of uploads* | | The minimum number of files a member must upload | | *Limit the max number of uploads* | | Set a maximum number of files a member can upload | | *Ask for caption* | | Allow members to add a caption to their upload | | *Require caption* | | Make the caption mandatory | | *Caption needs to include* | | Require specific words or phrases in the caption | | *Limit the maximum amount of characters* | | Set a character limit for captions | ### Post on Instagram Ask members to post on Instagram. Cevoid verifies the post before the task is marked complete and rewards are processed. **Available in:** Challenges, Single-task activities **How it works** 1. Member starts task 2. Member is asked to share their Instagram handle (skipped if already provided) 3. Member sees instructions and requirements 4. Member posts on Instagram and @mentions your account in the caption 5. Cevoid detects the post and verifies the task via Instagram's official API 6. Task is completed **Task specific settings** | Setting | Required | Description | | ---------------------------- | :------: | ------------------------------------------------------------------------------------------------------ | | *Allowed post type* | ✓ | Choose what post types are accepted: Image, Reel, Carousel album | | *Select content destination* | ✓ | Choose where submitted content is stored: Keep content in the submission, or Send content to the inbox | | *Must include hashtag* | | Require a specific hashtag in the post | | *Music / Sound* | ✓ | Choose: No music, or Allow music | *** ## Profile data Collect and use member information. | Task | Description | Challenges | Single-task activities | | ---------------------- | -------------------------------------------------------- | :--------: | :--------------------: | | **Profile properties** | Collect information about members | ✓ | ✓ | | **Become a member** | Automatically reward members when they join your program | | ✓ | ### Profile properties Collect information about members using profile properties. Use built-in properties like name, or create custom profile properties. **Available in:** Challenges, Single-task activities **How it works** 1. Member starts task 2. Member enters the requested information 3. Member clicks continue 4. Task is completed 5. Information is saved to the member's profile Measurements are entered in the member's unit system (metric or imperial) and automatically converted to your workspace default. There are multiple data types available for profile properties, from text and numbers to dates and measurements. See [Profile properties](/general/profiles/profile-properties) to explore what's possible and learn how to create and use them. **Task specific settings** This task has no settings. When adding this task, you select which profile property to collect. Settings related to each property are managed on the profile properties page. ### Become a member Automatically reward members when they join your program. **Available in:** Single-task activities This is a passive task, meaning members don't need to do anything. They automatically complete it when they join your program, and rewards are processed immediately. **Task specific settings** None. *** ## Base tasks Build custom forms and surveys with questions, inputs, and informational steps. Responses from base tasks are saved to submissions only. If you want to save data to member profiles as structured data and share with your CRM, use [Profile properties](#profile-properties) instead. | Task | Description | Challenges | Single-task activities | | -------------------------------- | ---------------------------------------------- | :--------: | :--------------------: | | **Single select & Multi select** | Let members pick from a list of options | ✓ | ✓ | | **Short text** | Ask for a single line of text | ✓ | ✓ | | **Long text** | Ask for longer, multi-line text | ✓ | ✓ | | **Number** | Ask for a number | ✓ | ✓ | | **Information** | Show a message without requiring input | ✓ | | | **Visit a link** | Drive traffic to a blog post or any other page | | ✓ | ### Single select & Multi select Ask members choice-based questions. Single select allows selecting one option, multi select allows selecting multiple options. **Available in:** Challenges, Single-task activities **How it works** 1. Member starts task 2. Member selects their answer(s) from the available options 3. Member clicks continue 4. Task is completed **Task specific settings** | Setting | Required | Description | | ------------------------------------- | :------: | ------------------------------------------------------------- | | *Choice type* | ✓ | Single select (one answer) or Multi select (multiple answers) | | *Multi selection (multi select only)* | | Unlimited, Exact number, or Range (min/max) | | *Display type* | ✓ | How options are displayed: Text or Color | | *Options* | ✓ | The available choices members can select from | ### Short text Collect single-line text responses from members, ideal for names, titles, or quick answers. **Available in:** Challenges, Single-task activities **How it works** 1. Member starts task 2. Member enters their response 3. Member clicks continue 4. Task is completed **Task specific settings** | Setting | Required | Description | | ------------------------------ | :------: | -------------------------------------- | | *Set minimum characters* | | Require a minimum number of characters | | *Limit the maximum characters* | | Set a maximum number of characters | ### Long text Collect multi-line text responses from members, ideal for feedback or detailed answers. **Available in:** Challenges, Single-task activities **How it works** 1. Member starts task 2. Member enters their response 3. Member clicks continue 4. Task is completed **Task specific settings** | Setting | Required | Description | | ------------------------------ | :------: | -------------------------------------- | | *Set minimum characters* | | Require a minimum number of characters | | *Limit the maximum characters* | | Set a maximum number of characters | ### Number Collect numeric input from members. **Available in:** Challenges, Single-task activities **How it works** 1. Member starts task 2. Member enters a number 3. Member clicks continue 4. Task is completed **Task specific settings** | Setting | Required | Description | | ----------- | :------: | --------------------- | | *Min value* | | Minimum value allowed | | *Max value* | | Maximum value allowed | ### Information Display information to members as a step in a challenge. **Available in:** Challenges **How it works** 1. Member reaches this step in the challenge 2. Member reads the information 3. Member continues to the next step **Task specific settings** | Setting | Required | Description | | ------------- | :------: | ------------------------------ | | *Title* | ✓ | The title displayed to members | | *Description* | | Text with your information | ### Visit a link Drive traffic to external pages by rewarding members who visit a link. **Available in:** Single-task activities **How it works** 1. Member clicks on the link button 2. The link opens in a new tab 3. Task is marked as completed after a 15-second delay Cevoid does not verify that a member actually visited the page. The 15-second delay encourages members to engage with the link before the task is marked as completed. **Task specific settings** | Setting | Required | Description | | ---------- | :------: | ------------------------------------- | | *Link* | ✓ | The URL members will visit | | *CTA text* | ✓ | The text displayed on the link button | *** ## Annual events Reward members on special dates each year. | Task | Description | Challenges | Single-task activities | | -------------------------- | ----------------------------------------------------------------- | :--------: | :--------------------: | | **Membership anniversary** | Reward members every year on their membership anniversary | | ✓ | | **Birthday** | Collect birthdates and reward members on their birthday each year | | ✓ | ### Membership anniversary Reward members every year on their membership anniversary. **Available in:** Single-task activities This is a passive task, meaning members don't need to do anything. Rewards are distributed each year on the date of their membership anniversary. **Task specific settings** None. ### Birthday Collect birthdates and reward members on their birthday each year. **Available in:** Single-task activities After members share their birthdate, this becomes a passive task. Rewards are automatically distributed every year on that date. Birthdays within 30 days of the date entered will not trigger rewards to prevent fraudulent behavior. For these members, rewards will be processed automatically from the following year onward. **How it works** 1. Member starts task 2. Member enters their birthdate 3. Member clicks continue 4. Task is completed 5. Birthdate is saved to the member's profile 6. Rewards are processed automatically every year on their birthday **Task specific settings** None. *** ## Social following & newsletter Grow your audience and email list. | Task | Description | Challenges | Single-task activities | | ----------------------------------- | ------------------------- | :--------: | :--------------------: | | **Klaviyo Newsletter subscription** | Build email list | | ✓ | | **Instagram handle** | Collect Instagram handles | ✓ | | | **Follow on Instagram** | Grow Instagram audience | | ✓ | | **Follow on TikTok** | Grow TikTok audience | | ✓ | | **Like Facebook page** | Grow Facebook audience | | ✓ | | **Follow on X** | Grow X audience | | ✓ | ### Klaviyo Newsletter subscription Build your email list by rewarding members who subscribe to your Klaviyo newsletter. **Available in:** Single-task activities **How it works** 1. Member enters their email (prefilled if known) and clicks subscribe 2. Task is completed 3. Cevoid creates the profile in Klaviyo if it doesn't already exist 4. Cevoid marks their profile as a marketing email subscriber in Klaviyo Members who are already subscribed can still complete this task. The only difference is that no change occurs in Klaviyo since they are already subscribed to your marketing emails. This task requires a connected Klaviyo account. See [Klaviyo](/integrations/klaviyo) to get started. **Task specific settings** | Setting | Required | Description | | ------- | :------: | ----------------------------------------------------------------------------- | | *List* | ✓ | The Klaviyo list members will be added to (one per connected Klaviyo account) | ### Instagram handle Collect and track member Instagram handles. **Available in:** Challenges **How it works** 1. Member starts task 2. Member enters their Instagram handle (prefilled if already shared) 3. Member clicks continue 4. Task is completed **Task specific settings** None. ### Follow on Instagram Grow your Instagram audience by rewarding members who follow your account. **Available in:** Single-task activities **How it works** 1. Member enters their Instagram handle (prefilled if already shared) 2. Member clicks on the follow button 3. Your Instagram account opens in a new tab 4. Task is marked as completed after a 15-second delay Instagram does not allow Cevoid to verify that a member has followed your account. The 15-second delay encourages members to complete the follow action before the task is marked as completed. **Task specific settings** | Setting | Required | Description | | --------------------------- | :------: | ------------------------------------------------------ | | *Handle* | ✓ | Your Instagram handle | | *Link to Instagram* | ✓ | Auto-generated link to your Instagram profile | | *CTA text* | ✓ | The text displayed on the follow button | | *Ask for Instagram handle* | | Request the member's Instagram handle | | *Instagram handle question* | | The question shown when asking for the member's handle | ### Follow on TikTok Grow your TikTok audience by rewarding members who follow your account. **Available in:** Single-task activities **How it works** 1. Member enters their TikTok handle (prefilled if already shared) 2. Member clicks on the follow button 3. Your TikTok account opens in a new tab 4. Task is marked as completed after a 15-second delay TikTok does not allow Cevoid to verify that a member has followed your account. The 15-second delay encourages members to complete the follow action before the task is marked as completed. **Task specific settings** | Setting | Required | Description | | ------------------------ | :------: | ------------------------------------------------------ | | *Handle* | ✓ | Your TikTok handle | | *Link to TikTok* | ✓ | Auto-generated link to your TikTok profile | | *CTA text* | ✓ | The text displayed on the follow button | | *Ask for TikTok handle* | | Request the member's TikTok handle | | *TikTok handle question* | | The question shown when asking for the member's handle | ### Like Facebook page Grow your Facebook audience by rewarding members who like your page. **Available in:** Single-task activities **How it works** 1. Member clicks on the like button 2. Your Facebook page opens in a new tab 3. Task is marked as completed after a 15-second delay Facebook does not allow Cevoid to verify that a member has liked your page. The 15-second delay encourages members to complete the like action before the task is marked as completed. **Task specific settings** | Setting | Required | Description | | ------------------ | :------: | ------------------------------------- | | *Link to Facebook* | ✓ | Link to your Facebook page | | *CTA text* | ✓ | The text displayed on the like button | ### Follow on X Grow your X audience by rewarding members who follow your account. **Available in:** Single-task activities **How it works** 1. Member enters their X handle (prefilled if already shared) 2. Member clicks on the follow button 3. Your X account opens in a new tab 4. Task is marked as completed after a 15-second delay X does not allow Cevoid to verify that a member has followed your account. The 15-second delay encourages members to complete the follow action before the task is marked as completed. **Task specific settings** | Setting | Required | Description | | ------------------- | :------: | ------------------------------------------------------ | | *Handle* | ✓ | Your X handle | | *Link to X* | ✓ | Auto-generated link to your X profile | | *CTA text* | ✓ | The text displayed on the follow button | | *Ask for X handle* | | Request the member's X handle | | *X handle question* | | The question shown when asking for the member's handle | # Challenges Source: https://docs.cevoid.com/program/activities/challenges Create multi-task activities to engage customers and run competitions. Related articles: [Activities overview](/program/activities/overview), [Available tasks](/program/activities/available-tasks), [Single-task activities](/program/activities/single-task-activities), [Available rewards](/program/available-rewards) Related widgets: [Activities](/program/on-site-widgets#activities) Related emails and triggers: [Challenge completed](/program/program-setup/program-emails-and-triggers#challenge-completed), [Challenge available](/program/program-setup/program-emails-and-triggers#challenge-available), [Reward fulfilled](/program/program-setup/program-emails-and-triggers#reward-fulfilled) Challenges are multi-task activities where members complete a series of steps to earn rewards. They're perfect for UGC campaigns, competitions, seasonal promotions, or collecting customer feedback. A challenge consists of three parts: the challenge information (title, dates, participants), the tasks members complete, and reward groups. With multiple tasks per challenge, you can get creative with how you engage members. Combine photo uploads with survey questions, ask for their Instagram handle while collecting profile properties, or build a multi-step campaign that tells a story. Reward groups are what make challenges powerful. You can reward participants with one set of rewards while also awarding different winners with bigger prizes, all in the same challenge. Challenges appear in your Activities program widget on your website, making it easy for members to participate directly from your store. Navigate to [Rewards program -> Activities](https://app.cevoid.com/program/activities) to manage your challenges. *** ## How a challenge works 1. Member starts the challenge 2. Member completes all required tasks and clicks submit 3. Submission is added to the challenge and the member's profile 4. Rewards are distributed according to the reward group settings Members can view their submissions by clicking on the challenge in the Activities widget. If they haven't reached the submission limit, they can click **New submission** to start another one. If a member leaves before completing a challenge, they can return and continue where they left off. *** ## Create a challenge 1. Navigate to [Rewards program -> Activities](https://app.cevoid.com/program/activities) 2. Click **New activity** 3. Select **Challenge** A live preview is available while you build your challenge, so you can see exactly what members will experience. Switch between desktop, tablet, and mobile to see the experience on different devices. *** ## Step 1: Tasks The **Tasks** tab is where you define what members need to do. Each challenge can include multiple tasks.