How to Customize the Widget Integration (Client)

Overview

This guide provides Technical Support teams with comprehensive instructions for customizing Widget Integration functionality using the window.boostWidgetIntegration API. All customizations are made through the customization.js file, which is accessible via the Code Editor in the Boost Admin App.

Prerequisites

• Access to Boost Admin App
• Basic understanding of JavaScript
• Familiarity with the shop's theme and requirements

Getting Started

Accessing the Customization File

1. Log into the Boost Admin App
2. Navigate to Code Editor
3. Open or create the customization.js file
4. All customizations must be wrapped in window.boostWidgetIntegration.onBeforeAppBootstrap

Basic Structure

window.boostWidgetIntegration.onBeforeAppBootstrap = () => {
  // All your customization code goes here
  window.boostWidgetIntegration.extend('ClassName', (BaseClass) => {
    return class CustomClass extends BaseClass {
      // Your custom implementation
    };
  });
};

Common Customization Scenarios

1. Customize the return value of a class method

Scenario: The customer wants to change the number of slides to show in the Recommendation carousel to 6

Problem: We need to change the slidesToShow setting of the RecommendationWidgetController

Reference:

• RecommendationWidgetController API Reference
• getCarouselConfig() method

Solution:

window.boostWidgetIntegration.onBeforeAppBootstrap = () => {
  window.boostWidgetIntegration.extend(
    'RecommendationWidgetController',
    (RecommendationWidgetController) => {
      return class CustomRecommendationWidgetController extends RecommendationWidgetController {
        getCarouselConfig(model) {
          // IMPORTANT: Call the parent method to get the base configuration
          const config = super.getCarouselConfig(model);

          // Modify the slidesToShow property
          config.slidesToShow = 6;

          // Return the modified configuration
          return config;
        }
      };
    },
  );
};

Explanation:

• We extend RecommendationWidgetController to create a custom class
• We override the getCarouselConfig() method
• We call super.getCarouselConfig(model) to get the default configuration
• We modify the slidesToShow property to 6
• We return the modified configuration

How to Test:

1. Save the customization code
2. Open browser DevTools → Network tab
3. Load a page with recommendation widgets
4. Scroll to the recommendation widget and verify that it shows 6 slides

---

2. Customize the parameters of a class method

Scenario: The customer wants to change the currency to "USD" for all Recommendation widgets

Problem: We need to change the currency parameter for Recommendation API calls

Reference:

• RecommendationAPI API Reference
• getRecommendation method

Solution:

window.boostWidgetIntegration.onBeforeAppBootstrap = () => {
  window.boostWidgetIntegration.extend('RecommendationAPI', (RecommendationAPI) => {
    return class CustomRecommendationAPI extends RecommendationAPI {
      getRecommendation(params, bodyPayload) {
        params.currency = 'USD'; // Force currency to USD

        // IMPORTANT: Call the parent method with modified params
        return super.getRecommendation(params, bodyPayload);
      }
    };
  });
};

Explanation:

• We extend RecommendationAPI to create a custom class
• We override the getRecommendation() method
• We modify the params object to set currency to "USD"
• We call super.getRecommendation(params, bodyPayload) to execute the original method with modified parameters

How to Test:

1. Save the customization
2. Open browser DevTools → Network tab
3. Load a page with recommendation widgets
4. Verify that the currency parameter in the API request is set to "USD"

---

Customization Reference

For complete API documentation including all available classes, methods, and properties, refer to the Widget Integration (Client) API Reference.

Troubleshooting

Widget Not Showing Customizations

Solution: Verify that the code is wrapped in window.boostWidgetIntegration.onBeforeAppBootstrap() and that there are no JavaScript errors in the console.

Best Practices

1. Always call parent methods: Use super.methodName() to preserve the base functionality
2. Handle edge cases: Add null checks and fallback values
3. Keep it simple: Start with small customizations and gradually build complexity

Getting Help

If you need assistance with customizations:

1. Check the browser console for error messages
2. Review this guide for similar examples
3. Contact Boost support with your customization code and the specific issue

---

Last Updated: January 2025 Version: 1.0