MantleClient

Building an app with Mantle involves a number of common tasks - identifying customers when they install, tracking how they use features, managing subscriptions, and controlling access to premium capabilities. While you can handle all of these with direct API calls, MantleClient provides a simpler path.

Think of MantleClient as your friendly interface to Mantle's API. It handles the repetitive stuff like managing authentication headers and provides consistent methods for common operations. This means you can focus on building your app's unique features instead of writing boilerplate API code.

🧪

If your app is built with React, check out MantleProvider.

Common integration patterns

When apps integrate with Mantle, they typically follow similar patterns. After a customer installs your app through Shopify's OAuth flow, you'll want to identify them to Mantle. From there, you might track how they use certain features, check if they're entitled to premium capabilities, or manage their subscription. MantleClient provides methods for all of these operations, each designed to work in either a backend or frontend context.

Two distinct contexts

Speaking of contexts, MantleClient operates differently depending on where you're using it. Let's look at both:

Backend operations

On your backend, you'll initialize MantleClient with your API key. This gives you access to administrative operations like identifying customers:

// Initialize with your API key for admin operations
const mantleClient = new MantleClient({
  appId: process.env.MANTLE_APP_ID,
  apiKey: process.env.MANTLE_API_KEY,
});

// Backend operations like customer identification
const response = await mantleClient.identify({
  platform: 'shopify',
  platformId: shop.id,
  myshopifyDomain: shop.myshopifyDomain,
  accessToken: shop.accessToken
});

const customerApiToken = response.apiToken;

Frontend operations

In your frontend code, you'll use a customer's API token instead. This limits operations to just what that specific customer should be able to do:

// Initialize with customer token for customer-specific operations
const mantleClient = new MantleClient({
  appId: process.env.MANTLE_APP_ID,
  customerApiToken: customerApiToken
});

// Customer-specific operations
const customer = await mantleClient.getCustomer();

Common use cases

Let's look at some typical ways you might use MantleClient in your app.

Managing features

Need to check if a customer has access to a specific feature? Or maybe you need to know how many products they can create? MantleClient makes these checks straightforward:

// Check if a feature is enabled
const hasFeature = await mantleClient.isFeatureEnabled({
  featureKey: 'custom_icons'
});

// Get limit for a feature
const limit = await mantleClient.limitForFeature({
  featureKey: 'product_limit'
});

Tracking usage

When a customer uses a feature, you'll want to track that usage - especially if you're doing usage-based billing:

// Send usage event
await mantleClient.sendUsageEvent({
  eventName: 'product_created',
  properties: {
    productId: '123',
    productType: 'physical'
  }
});

When to use direct API calls

While MantleClient makes many operations simpler, there are times when making direct API calls might make more sense. For instance, if you already have an API client structure in your app:

// Fits into existing API client
class YourApiClient {
  async getMantleCustomer() {
    return this.get('https://appapi.heymantle.com/v1/customer', {
      headers: {
        'X-Mantle-App-Id': process.env.MANTLE_APP_ID,
        'X-Mantle-Customer-Api-Token': customerApiToken
      }
    });
  }
}

Or if you want to minimize dependencies:

// No need to install additional package
const response = await fetch('https://appapi.heymantle.com/v1/identify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Mantle-App-Id': process.env.MANTLE_APP_ID,
    'X-Mantle-App-Api-Key': process.env.MANTLE_API_KEY,
  },
  body: JSON.stringify({
    platform: 'shopify',
    platformId: shop.id,
    myshopifyDomain: shop.myshopifyDomain
  })
});

Best practices

Security should always be top of mind when working with Mantle. Never expose your API key in frontend code - that's what customer API tokens are for. Use environment variables for sensitive values, and make sure you're using the right client for the right context and app. Each API key is tied to an app, so make sure to use the right API key for the production app and a different API key for each development app. Backend operations like customer identification should use your API key, while frontend operations should use customer tokens.

What's next?

Now that you understand MantleClient, you might want to dive into:

• The complete API reference for detailed endpoint documentation
• Our guide to Frontend integration if you're working with React
• How to implement Usage events to track customer behavior

Whether you choose to use MantleClient or direct API calls, the patterns and practices covered here will help you build a more robust integration with Mantle.