Documentation

This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Talon.One

Talon.One is a platform for creating, managing, and analyzing promotional marketing campaigns.

commercetools Frontend comes with an out-of-the-box Talon.One extension to integrate Talon.One in your commercetools Frontend project.

In this document, we'll walk you through how to set up the Talon.One extension and show an example use case.

Prerequisites

If the promotion-talon-one extension is not available in your commercetools Frontend project at this path packages/PROJECT_NAME/backend, before proceeding with the following configurations, you must:

  1. Clone the extension repository and add the code to your project.
  2. Register the extension in your project.

Out-of-the-box features

The following Talon.One features are supported:

Get started

To start using the Talon.One extension in your commercetools Frontend project, follow these steps:

  1. Add the following project configuration fields to the project schema from the Studio.

    Add Talon.One project configuration fieldsjson
    {
      "name": "Talon.One extension",
      "fields": [
        {
          "label": "HOST",
          "field": "EXTENSION_TALON_ONE_HOST",
          "type": "string",
          "translatable": false,
          "required": true
        },
        {
          "label": "API Key",
          "field": "EXTENSION_TALON_API_KEY_{CURRENCY}",
          "type": "string",
          "translatable": false,
          "required": true
        }
      ]
    }

    In Talon.One, Applications are environments where you create and manage your campaigns. Each Application has a single currency type and can have one or more API keys.

    If your Composable Commerce Project contains multiple currencies, you will need to create a Talon.One Application, including API key, for each currency you wish to support.

  2. Set the Talon.One configuration values from the Studio:

    • In the HOST field, enter your Talon.One deployment URL (for example, companyname.talon.one).
    • In the API Key field, enter the API key of your Talon.One Application.

Example

The following example shows how you can use Talon.One to apply discounts to a Cart. In our example, we will make changes to the addToCart action inside /backend/commerce-commercetools/actionControllers/CartController.ts.

First, we start a session by instantiating the TalonOnePromotionApi class, then update the Cart Line Items in the session, and finally, apply any returned effects.

export const addToCart: ActionHook = async (
  request: Request,
  actionContext: ActionContext
) => {
  const cartApi = getCartApi(request, actionContext);


  const body: {
    variant?: { sku?: string; count: number };
  } = JSON.parse(request.body);


  const lineItem: LineItem = {
    variant: {
      sku: body.variant?.sku || undefined,
      price: undefined,
    },
    count: +body.variant?.count || 1,
  };


  let cart = await CartFetcher.fetchCart(cartApi, request, actionContext);
  cart = await cartApi.addToCart(cart, lineItem);


  // Instantiate a Talon.One API session.
  const promotionApi = new TalonOnePromotionApi(
    actionContext.frontasticContext,
    cart.cartId, // Talon.One Session ID
    getLocale(request),
    getCurrency(request)
  );


  // Update the Cart Line Items in the Talon.One session.
  const promo = await promotionApi.updateCartItems(cart);


  // Apply any returned effects using DirectDiscounts.
  await cartApi.applyDiscountEffects(cart, promo.effects);


  const cartId = cart.cartId;


  const response: Response = {
    statusCode: 200,
    body: JSON.stringify(cart),
    sessionData: {
      ...request.sessionData,
      cartId,
    },
  };


  return response;
};

In the preceding example, the applyDiscountEffects method applies DirectDiscounts to the Cart based on the effects returned from Talon.One.

Additional features

You can access additional features such as giveaways, loyalty programs, and referrals by using the methods provided in the /backend/promotion-talon-one/apis/IntegrationApi.ts file. You can also add new methods and apply your own custom logic.