Settings

App settings are a means of providing a standardized model and UI for a merchant to configure an application’s behavior. When installed, a merchant can access your app-specific settings page within the Swell dashboard. Setting values managed by the merchant are then made available to the application in configurations and via API.

As a developer, you can configure settings using the same syntax as with Content fields. This approach offers allows you to fine-tune your app settings interface for various use cases, while offering an easy-to-use interface for merchants.

It’s possible to iterate on your application’s settings over time by introducing new fields and behavior. New setting fields are automatically added to an existing user’s schema as they upgrade their version of your app in the dashboard.

App settings are standardized way to present options for merchants to configure your application. Using the same field types as with content models, you can easily define a schema for your code to leverage and a user interface for merchants.

Here’s an example setting configuration for a product ranking system:

{
  "label": "Rankings",
  "description": "Manage settings that determine how rankings are calculated",
  "fields": [
    {
      "id": "update_product_rank",
      "type": "toggle",
      "label": "Automatically update product rankings",
      "default": false
    },
    {
      "id": "update_interval",
      "condition": "can_capture_metrics",
      "type": "radio",
      "label": "Update frequency",
      "options": [
        { "value": "continuously", "label": "Continuously" },
        { "value": "daily", "label": "Daily" }
      ]
      "default": "continuously"
    }
  ]
}

In this example, we introduce a toggle (boolean) setting update_product_rank that can be edited by a merchant in the admin dashboard. Note if your app has multiple setting configurations, they will be displayed in a grouped interface in the dashboard.

Your application can retrieve these settings on the fly to adapt your logic accordingly. Here’s an example of how to retrieve App settings using the Swell API:

await swell.get('/settings/<app_id>/ranking')

Another common approach is to act upon settings from an App function. Here’s an example that shows how to use settings to limit invocation of a function:

import { updateProductRank, updateProductRankDaily } from './lib/products';

export const config: SwellConfig = {
  description: 'Update product rankings',
  model: {
    collection: 'products',
    events: ['updated'],
    conditions: {
      $settings: {
        ranking: { update_product_rank: true },
      },
    },
  },
};

export default function (req: SwellRequest) {
  const { ranking: { update_interval } } = await req.swell.settings();

  if (update_interval === 'continuously') {
    await updateProductRank(req.data);
  } else if (update_interval === 'daily') {
    await updateProductRankDaily();
  }
}

In this example, we use the $settings property as a condition to match only when the update_product_rank setting is enabled.

During the lifecycle of an application, it is often necessary to add or deprecate settings. When your App is updated with new settings, the platform will automatically append those to the merchant’s existing configuration, maintaining existing setting values while adding new ones.

This approach allows developers to add new functionality over without affecting the integrity of existing user data.