Personalization

This section provides a guide to using the @archibald/personalization package, which provides a universal system for managing feature flags and personalized content.

Sections

• Architecture: A guide to the feature flag and personalization data flow.
• Setup: How to configure the personalization module and client.
• useFeatureFlag: Get detailed feature flag data.
• useFeatureFlagActive: Check if a feature is enabled.
• Personalization Adapters: An explanation of the adapter pattern and how to use different personalization adapters.

Installation

Run following to install @archibald/personalization package:

npm install @archibald/personalization

High-level Architecture

The @archibald/personalization package provides a PersonalizationClient and a set of hooks to interact with different personalization providers.

@archibald/personalization

The @archibald/personalization package provides:

• Universal Personalization Client: A unified API for interacting with feature flags and variant data.
• Isomorphic Personalization Hooks: useFeatureFlag and useFeatureFlagActive hooks that work on all platforms.
• Flexible Adapter Pattern: Pluggable adapters for different personalization providers.
• Server-Side Integration: Provides a PersonalizationModule for connecting to backend providers.

Minimum Setup

Application Side

When setting up the personalization package, you will need to create a PersonalizationClient in your application and configure it to use a predefined or custom adapter. The PersonalizationAdapter is the default adapter where you should extend from. The first prebuilt adapter is the GrowthBookAdapter which handles session and data transfer to the provider.

// shop/src/shop/client/api/creators/personalization.ts
import { PersonalizationClient } from '@archibald/personalization';
import { GrowthBookAdapter } from '@archibald/growthbook';
import { api } from 'shop/client/api';

export default new PersonalizationClient({
    adapter: GrowthBookAdapter,
    ttl: '10m',
    api
});

To access the PersonalizationClient in your application you will also need to pass it to a Client Provider. Usually it is added to the <App /> component.

// shop/src/shop/client/components/App.tsx
import { PersonalizationClientProvider } from '@archibald/personalization';

function App() {
    return (
        <PersonalizationClientProvider client={PersonalizationClient}>
            <AppLayout>
                <AppRoutes />
            </AppLayout>
        </PersonalizationClientProvider>
    );
}

NodeJS (Server Side)

On the NodeJS there is a PersonalizationModule which takes a personalization provider. Similar to the adapter, you can extend the PersonalizationProvider to create your own and integrate with a different 3rd party personalization system if needed. The current integrated system is Growthbook.

// shop/src/shop/server/module/server.tsx

class Server extends CoreServer {
    public async initModules() {
        const { hybris } = this.configService.get();
        await this.registerModules([
            new PersonalizationModule({ 
                provider: new GrowthBookProvider({ 
                    config: {
                        apiHost: 'https://growthbook.netconomy.net/',
                        clientKey: 'key',
                        streaming: true
                    }
                }) 
            }),
        ]);
    }
}

Example: Using a Feature Flag

Here is a simple example of how to use the useFeatureFlagActive hook to toggle a feature:

import { useFeatureFlagActive } from '@archibald/personalization';

function NewCheckoutFeature() {
    const isEnabled = useFeatureFlagActive('new-checkout-flow');

    if (isEnabled) {
        return <ModernCheckout />;
    }
    return <LegacyCheckout />;
}