Third-party Integration

Introduction

Enhancing your Weaverse Hydrogen theme with third-party applications allows you to add specialized functionality such as product reviews, advanced analytics, marketing tools, and content enrichment. Weaverse’s flexible architecture makes it possible to integrate with virtually any external service that offers a public API or React component library. This guide provides a comprehensive approach to integrating third-party services with your Weaverse Hydrogen store, with real-world examples and proven patterns that maintain performance and user experience.

Integration Methods

Weaverse supports two primary approaches for integrating third-party applications:

Using the App’s Component Library

Many third-party applications provide React components that you can incorporate directly into your Weaverse sections:

Install the Library

npm install @third-party-app/react
# or
yarn add @third-party-app/react

Create a Custom Section Component

// app/sections/third-party-widget/index.tsx
import { ThirdPartyComponent } from '@third-party-app/react'
import type { SectionProps } from '~/components/section'
import { Section } from '~/components/section'
import { forwardRef } from 'react'

export type ThirdPartyWidgetProps = {
  // Public, non-secret identifier only. Never put private API keys or tokens
  // in section props or Studio settings: they are saved with page data and
  // rendered into public markup.
  widgetId: string
}

const ThirdPartyWidget = forwardRef<HTMLElement, SectionProps & ThirdPartyWidgetProps>(
  (props, ref) => {
    const { widgetId, ...rest } = props
    
    return (
      <Section ref={ref} {...rest}>
        <ThirdPartyComponent widgetId={widgetId} />
      </Section>
    )
  }
)

export default ThirdPartyWidget

If the app requires a private API key or token, keep it in a server environment variable and call the app’s API from a loader, as shown in the Querying App Data from App’s API section below and the Judge.me reviews guide. Only publishable, browser-safe identifiers belong in Studio settings.

Define the Schema

// app/sections/third-party-widget/schema.ts
import { createSchema } from '@weaverse/hydrogen'

export let schema = createSchema({
  type: 'third-party-widget',
  title: 'Third Party Widget',
  settings: [
    {
      group: 'Widget Settings',
      inputs: [
        {
          type: 'text',
          name: 'widgetId',
          label: 'Widget ID',
          defaultValue: '',
          helpText: 'Public widget ID from the third-party dashboard. Do not enter secret keys here.',
        },
        // Additional configuration inputs
      ]
    }
  ],
  presets: {
    children: [
      // Default children if needed
    ]
  }
})

Register the Section in Weaverse Ensure your component is registered in your Weaverse configuration file:

// app/weaverse/sections.ts
import ThirdPartyWidget from '~/sections/third-party-widget'
import { schema as thirdPartyWidgetSchema } from '~/sections/third-party-widget/schema'

export const sections = {
  // Other sections
  'third-party-widget': {
    Component: ThirdPartyWidget,
    schema: thirdPartyWidgetSchema
  }
}

Querying App Data from App’s API

For third-party services that offer a REST or GraphQL API, Weaverse’s loader pattern provides an elegant way to fetch and incorporate external data:

Store API Credentials Securely Add your API credentials to your environment variables:
# .env THIRD_PARTY_API_KEY=your_secret_key_here

Implement a Component Loader

// app/sections/api-widget/index.tsx
import type { ComponentLoaderArgs } from '@weaverse/hydrogen'
import { createSchema } from '@weaverse/hydrogen'
import { forwardRef } from 'react'
import { Section, type SectionProps } from '~/components/section'

type ApiWidgetData = {
  resourceId: string
  itemsToShow: number
}

export const loader = async ({ weaverse, data }: ComponentLoaderArgs<ApiWidgetData>) => {
  const { fetchWithCache, env, storefront } = weaverse
  const { resourceId, itemsToShow = 5 } = data

  if (!resourceId) return { items: [] }
  
  try {
    return await fetchWithCache(
      `https://api.third-party.com/resources/${resourceId}?limit=${itemsToShow}`,
      {
        headers: {
          'Authorization': ['Bearer', env.THIRD_PARTY_API_KEY].join(' '),
          'Content-Type': 'application/json'
        },
        // Use Hydrogen's caching to optimize performance
        strategy: storefront.CacheShort()
      }
    )
  } catch (error) {
    console.error('Error fetching data:', error)
    return { items: [], error: true }
  }
}

type ApiWidgetProps = SectionProps<Awaited<ReturnType<typeof loader>>> & ApiWidgetData

const ApiWidget = forwardRef<HTMLElement, ApiWidgetProps>((props, ref) => {
  const { loaderData, resourceId, itemsToShow, ...rest } = props
  const { items, error } = loaderData || { items: [] }

  if (error) {
    return (
      <Section ref={ref} {...rest}>
        <div className="p-4 text-center text-red-500">
          Unable to load content from external API
        </div>
      </Section>
    )
  }
  
  return (
    <Section ref={ref} {...rest}>
      <div className="grid gap-4 grid-cols-1 md:grid-cols-3">
        {items.map((item) => (
          <div key={item.id} className="border p-4 rounded">
            <h3>{item.title}</h3>
            <p>{item.description}</p>
          </div>
        ))}
      </div>
    </Section>
  )
})

export default ApiWidget

export let schema = createSchema({
  type: 'api-widget',
  title: 'API Widget',
  settings: [
    {
      group: 'API Settings',
      inputs: [
        {
          type: 'text',
          name: 'resourceId',
          label: 'Resource ID',
          defaultValue: '',
          shouldRevalidate: true, // This triggers data refresh when changed
        },
        {
          type: 'range',
          name: 'itemsToShow',
          label: 'Items to Show',
          defaultValue: 5,
          shouldRevalidate: true,
          configs: {
            min: 1,
            max: 20,
            step: 1
          }
        }
      ]
    }
  ]
})

Data Fetching Patterns

Weaverse provides multiple approaches to fetch data from third-party services, each with its own advantages.

Server Component Integration

Server-side data fetching is the preferred approach for most integrations as it keeps API keys secure and reduces client-side JavaScript:

export const loader = async ({ weaverse, data }: ComponentLoaderArgs<WidgetData>) => {
  const { fetchWithCache, env } = weaverse
  
  return await fetchWithCache('https://api.third-party.com/data', {
    headers: {
      'Authorization': ['Bearer', env.API_KEY].join(' ')
    }
  })
}

Benefits:

API keys remain secure on the server
Reduced JavaScript bundle size
Better performance for initial page load
SEO-friendly as content is included in the initial HTML

Client Component Integration

Some third-party widgets require client-side initialization:

// app/sections/analytics-widget/client.tsx
'use client'

import { useEffect } from 'react'

export function AnalyticsClient({ trackingId }) {
  useEffect(() => {
    // Load analytics script
    const script = document.createElement('script')
    script.src = `https://analytics.example.com/script.js?id=${trackingId}`
    script.async = true
    document.head.appendChild(script)
    
    return () => {
      // Clean up on unmount
      const existingScript = document.querySelector(`script[src*="analytics.example.com"]`)
      if (existingScript && existingScript.parentNode) {
        existingScript.parentNode.removeChild(existingScript)
      }
    }
  }, [trackingId])
  
  return null // This component doesn't render anything visible
}

Use this approach when:

The integration requires browser-specific APIs
The third-party service needs to track user interactions
The widget needs to be initialized after the page loads

Hybrid Integration

Combine server and client approaches for the best of both worlds:

// Server component that fetches data
export const loader = async ({ weaverse, data }: ComponentLoaderArgs<WidgetData>) => {
  // Fetch initial data server-side
  return await weaverse.fetchWithCache('https://api.third-party.com/initial-data')
}

// Main component
const HybridWidget = forwardRef((props, ref) => {
  const { loaderData, settings } = props
  
  return (
    <div ref={ref}>
      {/* Render server-fetched data */}
      <ServerRenderedContent data={loaderData} />
      
      {/* Include client component for interactivity */}
      <ClientInteractivity initialData={loaderData} settings={settings} />
    </div>
  )
})

// Client component for interactive features
'use client'
function ClientInteractivity({ initialData, settings }) {
  const [data, setData] = useState(initialData)
  
  // Client-side interactions and updates
  // ...
  
  return (
    <div className="interactive-elements">
      {/* Interactive UI elements */}
    </div>
  )
}

This pattern is ideal for:

Review systems that need initial content rendered server-side but allow client-side submissions
Interactive widgets that need to show initial data quickly but then become interactive
Progressive enhancement scenarios

Real-World Examples

For a complete, theme-independent Judge.me walkthrough, see the dedicated guide:

Integrate Judge.me Reviews with Shopify Hydrogen

Keep the private API key on the server, proxy review data through Hydrogen, and expose the UI as an editable Weaverse section.

Common Integration Challenges

Authentication

Most third-party APIs require authentication. Here are the common approaches:

API Key Authentication

export let loader = async ({ weaverse }: ComponentLoaderArgs) => {
  const { env } = weaverse
  
  return await weaverse.fetchWithCache('https://api.example.com/data', {
    headers: {
      'Authorization': ['Bearer', env.THIRD_PARTY_API_KEY].join(' ')
    }
  })
}

OAuth Integration For services using OAuth:

export let loader = async ({ weaverse, context }: ComponentLoaderArgs) => {
  const { session } = context
  const accessToken = await session.get('thirdPartyAccessToken')
  
  if (!accessToken) {
    // Handle unauthenticated state
    return { authenticated: false }
  }
  
  return await weaverse.fetchWithCache('https://api.example.com/data', {
    headers: {
      'Authorization': ['Bearer', accessToken].join(' ')
    }
  })
}

Rate Limiting

Prevent rate limit issues by implementing proper caching:

export let loader = async ({ weaverse }: ComponentLoaderArgs) => {
  const { fetchWithCache, storefront } = weaverse
  
  return await fetchWithCache('https://rate-limited-api.example.com/data', {
    // Use longer cache times for rate-limited APIs
    strategy: storefront.CacheCustom({
      maxAge: 600, // 10 minutes
      staleWhileRevalidate: 3600, // 1 hour
      staleIfError: 86400 // 1 day - use stale data on errors
    })
  })
}

Error Handling

Implement robust error handling for third-party services:

export let loader = async ({ weaverse }: ComponentLoaderArgs) => {
  const { fetchWithCache } = weaverse
  
  try {
    const response = await fetchWithCache('https://api.third-party.com/data')
    
    // Validate response structure
    if (!response || !response.data) {
      console.warn('Invalid response format from API')
      return { data: [], error: 'invalid_format' }
    }
    
    return { data: response.data, error: null }
  } catch (error) {
    console.error('API error:', error)
    
    // Different error handling based on error type
    if (error instanceof Response) {
      if (error.status === 429) {
        return { data: [], error: 'rate_limited' }
      } else if (error.status >= 500) {
        return { data: [], error: 'service_unavailable' }
      }
    }
    
    return { data: [], error: 'unknown' }
  }
}

Data Synchronization

For widgets that need to stay in sync with your store data:

export let loader = async ({ weaverse, data }: ComponentLoaderArgs<WidgetData>) => {
  const { storefront, fetchWithCache } = weaverse
  const { productId } = data
  
  // First get the product data from Shopify
  const { product } = await storefront.query(`
    query Product($id: ID!) {
      product(id: $id) {
        id
        title
        updatedAt
      }
    }
  `, {
    variables: { id: productId }
  })
  
  // Then get related data from third-party
  const externalData = await fetchWithCache(
    `https://api.third-party.com/products/${productId}`,
    {
      // Include product updated timestamp to maintain consistency
      body: JSON.stringify({ 
        productUpdatedAt: product.updatedAt
      })
    }
  )
  
  return {
    product,
    externalData
  }
}

Performance Optimization

Caching Strategies

The choice of caching strategy depends on how frequently your third-party data changes:

// For rarely changing data (e.g., product descriptions)
strategy: storefront.CacheLong()

// For frequently changing data (e.g., inventory, prices)
strategy: storefront.CacheShort()

// For personalized or dynamic content
strategy: storefront.CacheNone()

// For custom requirements
strategy: storefront.CacheCustom({
  maxAge: 300, // 5 minutes
  staleWhileRevalidate: 1800, // 30 minutes
  staleIfError: 86400, // 1 day
  mode: 'public'
})

Selective Loading

Only load what’s needed when it’s needed:

export let loader = async ({ weaverse, data }: ComponentLoaderArgs<WidgetData>) => {
  const { fetchWithCache, request } = weaverse
  const { widgetType, itemsToShow } = data
  
  // Determine if this is a viewport-visible request
  const url = new URL(request.url)
  const isVisible = url.searchParams.get('visible') === 'true'
  
  // Only fetch data if component is visible
  if (!isVisible) {
    return { deferred: true }
  }
  
  return await fetchWithCache(
    `https://api.third-party.com/widget/${widgetType}?limit=${itemsToShow}`
  )
}

Lazy Loading

Use client components to defer loading of non-critical third-party widgets:

'use client'
import { useEffect, useState } from 'react'

export function LazyThirdPartyWidget({ config }) {
  const [isVisible, setIsVisible] = useState(false)
  const [isLoaded, setIsLoaded] = useState(false)
  
  useEffect(() => {
    // Set up intersection observer
    const observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        setIsVisible(true)
        observer.disconnect()
      }
    })
    
    // Observe the component's container
    const container = document.getElementById('widget-container')
    if (container) {
      observer.observe(container)
    }
    
    return () => observer.disconnect()
  }, [])
  
  useEffect(() => {
    // Load the widget when it becomes visible
    if (isVisible && !isLoaded) {
      const script = document.createElement('script')
      script.src = 'https://third-party.com/widget.js'
      script.onload = () => {
        window.ThirdPartyWidget.initialize(config)
        setIsLoaded(true)
      }
      document.head.appendChild(script)
    }
  }, [isVisible, isLoaded, config])
  
  return (
    <div id="widget-container" className="min-h-[200px]">
      {!isLoaded && <div className="loading-placeholder" />}
      <div id="third-party-widget-target" />
    </div>
  )
}

Security Best Practices

When integrating third-party services, follow these security practices:

Keep API Keys Secure
- Never hardcode API keys in your components
- Use environment variables accessible only on the server
- Consider using Shopify’s app proxy for sensitive operations
Validate All External Data
- Validate and sanitize all data from third-party APIs
- Be defensive against malformed responses
- Never directly inject external content into your DOM
Implement Content Security Policy (CSP)
- Restrict which domains can serve scripts to your site
- Use nonces or hashes for inline scripts from trusted sources
- Monitor CSP violations to detect potential issues
Minimize Access and Permissions
- Only request the permissions needed for your integration
- Use read-only access when possible
- Regularly review and rotate API keys

Troubleshooting

Common issues and their solutions:

API Returns Errors

Check if your API key is valid and has the correct permissions
Verify that you’re using the correct API endpoint
Look for rate limiting or quota issues

Solution:

try {
  // Make your API call here
} catch (error) {
  console.error('API Error:', error)
  
  // Check specific error types
  if (error.message.includes('rate limit')) {
    // Handle rate limiting
  } else if (error.message.includes('authentication')) {
    // Handle auth issues
  }
}

Component Fails to Render

Check browser console for JavaScript errors
Verify that the third-party script loaded successfully
Ensure your component handles the absence of data gracefully

Solution:

const Widget = forwardRef((props, ref) => {
  const { loaderData } = props
  
  // Always check if data exists before rendering
  if (!loaderData || loaderData.error) {
    return (
      <div ref={ref} className="error-container">
        <p>Unable to load widget. Please try again later.</p>
      </div>
    )
  }
  
  // Proceed with normal rendering
})

Hydration Mismatch Errors

Ensure server and client rendering produce the same output
Defer client-specific code to useEffect hooks
Use client components with careful boundaries

Solution:

'use client'
import { useEffect, useState } from 'react'

export function ClientWidget({ initialData }) {
  // Start with initial data from server
  const [data, setData] = useState(initialData)
  
  // Add client-side behavior after mount
  useEffect(() => {
    // Client-only code here
  }, [])
  
  return <div>{/* Render using data */}</div>
}

Conclusion

Third-party integrations can significantly enhance your Weaverse Hydrogen store with specialized functionality that would be time-consuming to build from scratch. By following the patterns and best practices in this guide, you can create seamless integrations that enhance your store without compromising performance or user experience. Weaverse’s flexible architecture allows for integration with virtually any third-party service that offers a public API, making your store infinitely extensible. Whether you’re adding product reviews, analytics, marketing tools, or content enrichment, the component-based approach and powerful data fetching capabilities give you everything you need to build a truly custom e-commerce experience.

Environment

Building Components

Content Management

Internationalization

Security & Privacy

Pages & Routing

Advanced

Deployment

Third-party Integration

Third-party Integration

Introduction

Integration Methods

Using the App’s Component Library

Querying App Data from App’s API

Data Fetching Patterns

Server Component Integration

Client Component Integration

Hybrid Integration

Real-World Examples

Integrate Judge.me Reviews with Shopify Hydrogen

Common Integration Challenges

Authentication

Rate Limiting

Error Handling

Data Synchronization

Performance Optimization

Caching Strategies

Selective Loading

Lazy Loading

Security Best Practices

Troubleshooting

Conclusion

​Third-party Integration

​Introduction

​Integration Methods

​Using the App’s Component Library

​Querying App Data from App’s API

​Data Fetching Patterns

​Server Component Integration

​Client Component Integration

​Hybrid Integration

​Real-World Examples

Integrate Judge.me Reviews with Shopify Hydrogen

​Common Integration Challenges

​Authentication

​Rate Limiting

​Error Handling

​Data Synchronization

​Performance Optimization

​Caching Strategies

​Selective Loading

​Lazy Loading

​Security Best Practices

​Troubleshooting

​Conclusion

Third-party Integration

Introduction

Integration Methods

Using the App’s Component Library

Querying App Data from App’s API

Data Fetching Patterns

Server Component Integration

Client Component Integration

Hybrid Integration

Real-World Examples

Common Integration Challenges

Authentication

Rate Limiting

Error Handling

Data Synchronization

Performance Optimization

Caching Strategies

Selective Loading

Lazy Loading

Security Best Practices

Troubleshooting

Conclusion