DOCSEARCHbyAlgolia
Submit Docs

Contribe Documentation

website·Indexed 34 days ago

https://docs.contribe.io

Guides for integrating and styling the Contribe plugin, including setup instructions for Upcart and WooCommerce, custom cart completion analytics, and component customization using CSS variables.

Tokens
3.1K
Snippets
16
Records
18
Agent score
50%

What's inside Contribe

  1. Apply instance-specific styles using the styleOverride attribute

    For LIT components, the styleOverride attribute allows you to inject custom CSS rules directly into the component's shadow DOM. This is useful for instance-specific styling, dynamic runtime styles, or customizing components without modifying global CSS or source code. Because these styles are injected into the shadow DOM, you may need to use !important to ensure your overrides take precedence.
    <!-- Example: Overriding the project button color to red for a specific plugin instance -->
<contribe-plugin styleOverride=".contribe-selector-project-button { color: red !important; }"/>

  2. Set up the Contribe plugin in WordPress

    Follow these steps to activate the Contribe integration within your WordPress admin dashboard:

    1. Navigate to Plugins > Add New Plugin.
    2. Click Add Plugin and upload the contribe-woocommerce-plugin.zip file.
    3. Once uploaded, click Activate Plugin.
    4. Navigate to the new Contribe.io section in the WordPress UI.
    5. Enter the following credentials provided by the Contribe team:
      • Plugin ID: The unique identifier for your plugin.
      • Secret Key: The unique key used to synchronize order information.

  3. Track carts and orders for custom webshops

    While the WooCommerce plugin syncs order data automatically via a Secret Key, custom webshops must manually pass cart context to the plugin and notify Contribe when a cart is completed using the contribe-cart-update event and the cart completion endpoint.

  4. Install the Contribe plugin in a webshop

    To add the Contribe plugin to your site, you must include the plugin script in your document head and place the <contribe-plugin> custom element in the HTML where you want the widget to appear. You must replace XXXXXXXX with your unique Plugin ID. For Shopify users, the Plugin ID is your .myshopify.com domain.
    <!-- Add the script to your head or next to other scripts -->
<script>
const scriptTag = document.createElement("script");
scriptTag.type = "module";
scriptTag.src = "https://plugins.contribe.io/cdn/v1/plugin.mjs";
document.head.appendChild(scriptTag);
</script>

<!-- Add this to your HTML where you would like the widget to appear -->
<contribe-plugin
  pluginId="XXXXXXXX"
  locale="inherit"
  logo="true"
/>

  5. Integrate Contribe plugin with Upcart

    To set up the Contribe plugin within an Upcart environment, you must identify the Upcart element (typically #upCart), locate the .upcart-products-section within its shadow root or element tree, and append a <contribe-plugin> element. The pluginId attribute of the plugin should be set to the Shopify shop ID, which can be retrieved from window.Shopify.shop or window.__NEXT_DATA__.props.pageProps.shop. Finally, load the Contribe plugin module from the CDN.
    <script type="module">
    const upcart = document.getElementById("upCart");

    if (upcart) {
        const element = upcart?.shadowRoot ?? upcart;
        const target = element?.querySelector(".upcart-products-section");
        const shopId = window?.Shopify?.shop ?? window?.__NEXT_DATA__?.props?.pageProps?.shop

        if (target) {
            const plugin = document.createElement("contribe-plugin");
            plugin.setAttribute("pluginId", shopId);
            target.appendChild(plugin);

            const script = document.createElement("script");
            script.src = "https://plugins.contribe.io/cdn/v1/plugin.mjs";
            script.type = "module";
            document.head.appendChild(script);
        }
    }
</script>

  6. Update cart properties dynamically via DOM events

    For custom shop setups, you can update cart data at any time by dispatching a contribe-cart-update CustomEvent on the document. The plugin will store these values internally and include them in all subsequent analytics calls.
    document.dispatchEvent(new CustomEvent("contribe-cart-update", {
  detail: {
    cartId: "abc123",
    cartSize: 3,
    cartValue: 129.95,
  },
}));

  7. Customize Contribe components using CSS variables

    Contribe components are customizable via CSS custom properties. You can override these variables by redeclaring them in a parent element or within the component's host to change colors, fonts, spacing, and animations without modifying the underlying CSS.
    :host {
  --contribe-primary-color: #007bff; /* Change primary color to blue */
}

  8. Install and configure the Contribe WooCommerce plugin

    To integrate Contribe with WooCommerce, you must install the dedicated WordPress plugin and configure it with credentials provided by the Contribe team. Note that order data is synced automatically via the Secret Key, so manual cart tracking configuration is not required for WooCommerce.
    # 1. Download the plugin zip file: contribe-woocommerce-plugin.zip

  9. Style project description boxes

    These variables control the appearance of the project description area, including the header, body text, and the container box.
    /* Project Description */
--contribe-project-header-font-size: var(--contribe-font-small);
--contribe-project-description-font-size: var(--contribe-font-small);
--contribe-project-description-padding: 5px;
--contribe-project-description-color: var(--contribe-primary-color);
--contribe-project-description-background: var(--contribe-secondary-color);
--contribe-project-description-border-radius: var(--contribe-border-radius);
--contribe-project-description-border: var(--contribe-border);
--contribe-project-description-margin: 0 0;
--contribe-project-link-color: inherit;

  10. Customize selector header and project description styles via CSS variables

    Contribe components use CSS variables for customization. The following variables control the appearance of the selector header and project description elements:
    /* Selector Header */
--contribe-selector-header-title-font-size: var(--contribe-font-large); /* Font size for the selector header title */
--contribe-selector-header-description-font-size: var(--contribe-font-small); /* Font size for the selector header description */
--contribe-selector-header: var(--contribe-primary-color); /* Overall color for the selector header */
--contribe-selector-header-checkbox: var(--contribe-primary-color); /* Color for checkboxes in the header */
--contribe-selector-header-title: var(--contribe-primary-color); /* Color for the header title text */
--contribe-selector-header-description: var(--contribe-primary-color); /* Color for the header description text */

/* Project Descriptions */
--contribe-selector-project-description-title: var(--contribe-primary-color); /* Color for the title text within project descriptions */
--contribe-selector-project-description-description: var(--contribe-primary-color); /* Color for the description text within project descriptions */

  11. Style the Contribe plugin using CSS variables

    The Contribe plugin is styled using CSS variables targeted at the contribe-plugin element. You can customize font sizes, colors, borders, padding, and border-radius by modifying these variables in your stylesheet.
    contribe-plugin {
  display: block;

  /* Container Styles */
  --contribe-container-background: inherit;
  --contribe-container-border: none;
  --contribe-container-padding: 0px;
  --contribe-container-border-radius: none;

  /* Typography */
  --contribe-font-large: 12px;
  --contribe-font-small: 10px;

  /* Project Item Styles */
  --contribe-project-background: #f5f5f5;
  --contribe-project-active-background: #000000;
  --contribe-project-description-background: #000000;
  --contribe-project-icon-size: 24px;
  --contribe-project-icon-color: inherit;
  --contribe-project-active-icon-color: #ffffff;
  --contribe-project-padding: 2px;
  --contribe-project-border-radius: 1px;
  --contribe-project-border: 1px solid #000000;

  /* Project Description Styles */
  --contribe-project-description-border-radius: 1px;
  --contribe-project-description-border: 1px solid #000000;
  --contribe-project-description-padding: 5px;

  /* Header Text Colors */
  --contribe-selector-header-title: #000;
  --contribe-selector-header-description: #000;

  /* Project Description Text Colors */
  --contribe-selector-project-description-title: #ffffff;
  --contribe-selector-project-description-description: #ffffff;
}

  12. Configure global styling variables

    Global variables control the overall look and feel across all components. Key variables include primary/secondary colors, base fonts, and border styles.
    /* Global Settings */
--contribe-line-height: 1.5;               /* Default line height */
--contribe-primary-color: #000;            /* Text, icons, and highlights */
--contribe-secondary-color: #fff;          /* Backgrounds or contrasts */
--contribe-border: 1px solid #000;          /* Default border style */
--contribe-border-radius: 1px;             /* Border radius */
--contribe-font: inherit;                   /* Base font family */
--contribe-font-large: max(0.9rem, 11px);  /* Larger text size */
--contribe-font-small: max(0.8rem, 10px);  /* Smaller text size */