QuickStart: Explore it with Node.js

This quickstart guide will help you deploy the FE&R Decision API locally and interact with it using Node.js. You'll learn how to make API calls, manage visitor sessions, and implement feature flag.

Prerequisites

• Node.js 14.x or higher

• Docker and Docker Compose installed

• FE&R Account with Environment ID and API Key

Step 1: Start the Decision API

Quick Start with Docker Compose

1. Create a project directory:

mkdir flagship-quickstart
cd flagship-quickstart

1. Create a docker-compose.yml file:

version: "3.9"

services:
  redis:
    image: redis:7-alpine
    container_name: flagship-redis
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped

  decision-api:
    image: flagshipio/decision-api:latest
    container_name: flagship-decision-api
    ports:
      - "8080:8080"
    environment:
      ENV_ID: YOUR_ENV_ID
      API_KEY: YOUR_API_KEY
      LOG_LEVEL: debug
      CACHE_TYPE: redis
      CACHE_OPTIONS_REDISHOST: redis:6379
    depends_on:
      - redis
    restart: unless-stopped

volumes:
  redis-data:
    driver: local

networks:
  default:
    name: flagship-demo

1. Replace credentials:

Replace YOUR_ENV_ID and YOUR_API_KEY with your actual FE&R credentials from https://app2.abtasty.com

1. Start the services:

docker compose up -d

Step 2: Set Up Your Node.js Project

# Install axios for making HTTP requests
npm init -y
npm install axios

# Create examples directory
mkdir examples

---

REST APIs

The Decision API provides simple REST endpoints. Below are practical examples of how to use each endpoint.

Start an HTTP Session

In Flagship, a visitor "session" is simply making API calls with a unique visitor ID. The visitor ID should be consistent across requests to enable features like Experience Continuity.

Example: Fetch Campaigns for a Visitor

Create examples/get-campaigns.js:

const axios = require('axios');

const API_URL = 'http://localhost:8080';

async function getCampaigns() {
  try {
    // Define visitor information
    const visitorId = 'user_123456';
    const context = {
      platform: 'web',
      device_type: 'desktop',
      location: 'US'
    };

    console.log(`📍 Fetching campaigns for visitor: ${visitorId}`);
    console.log('   Context:', context);

    // Call POST /v2/campaigns
    const response = await axios.post(
      `${API_URL}/v2/campaigns`,
      {
        visitor_id: visitorId,
        context: context,
        trigger_hit: false
      },
      {
        headers: { 'Content-Type': 'application/json' }
      }
    );

    const campaigns = response.data.campaigns || [];
    console.log(`\n✅ Received ${campaigns.length} campaign(s)\n`);

    // Display each campaign
    campaigns.forEach((campaign, index) => {
      console.log(`Campaign ${index + 1}:`);
      console.log(`  ID: ${campaign.id}`);
      console.log(`  Type: ${campaign.type}`);
      console.log(`  Variation: ${campaign.variation.name}`);
      console.log(`  Values:`, campaign.variation.modifications.value);
      console.log('');
    });

    return campaigns;
  } catch (error) {
    console.error('❌ Error:', error.message);
    throw error;
  }
}

// Run the example
getCampaigns();

Run it:

node examples/get-campaigns.js

Example: Activate a Campaign

When a visitor sees a variation, you must activate it to send analytics data to Flagship.

Create examples/activate-campaign.js:

const axios = require('axios');

const API_URL = 'http://localhost:8080';
const ENV_ID = 'ENV_ID';

async function activateCampaign() {
  try {
    const visitorId = 'user_123456';

    // First, get campaigns
    const campaignsResponse = await axios.post(
      `${API_URL}/v2/campaigns`,
      {
        visitor_id: visitorId,
        context: { platform: 'web' }
      }
    );

    const campaigns = campaignsResponse.data.campaigns || [];
    
    if (campaigns.length === 0) {
      console.log('⚠️  No campaigns to activate');
      return;
    }

    const campaign = campaigns[0];
    console.log(`⚡ Activating campaign: ${campaign.id}`);

    // Call POST /v2/activate
    await axios.post(
      `${API_URL}/v2/activate`,
      {
        cid: ENV_ID,
        vid: visitorId,
        caid: campaign.variationGroupId,
        vaid: campaign.variation.id
      },
      {
        headers: { 'Content-Type': 'application/json' }
      }
    );

    console.log('✅ Campaign activated successfully');
  } catch (error) {
    console.error('❌ Error:', error.message);
  }
}

// Run the example
activateCampaign();

Run it:

node examples/activate-campaign.js

Run a Feature Flag

Feature flags allow you to control features and A/B test variations. The /v2/flags endpoint provides a flag-oriented view of your campaigns.

Example: Get Feature Flags

Create examples/get-flags.js:

const axios = require('axios');

const API_URL = 'http://localhost:8080';

async function getFlags() {
  try {
    const visitorId = 'user_123456';
    const context = {
      platform: 'web',
      user_type: 'premium'
    };

    console.log(`🚩 Fetching flags for visitor: ${visitorId}\n`);

    // Call POST /v2/flags
    const response = await axios.post(
      `${API_URL}/v2/flags`,
      {
        visitor_id: visitorId,
        context: context
      },
      {
        headers: { 'Content-Type': 'application/json' }
      }
    );

    const data = response.data || [];

    console.log(`✅ Received ${JSON.stringify(Object.keys(data).length)} flag(s)\n`)

    // Display each flag
    Object.keys(data).forEach(key => {
      const flag = data[key];
      console.log(`Flag: ${key}`);
      console.log(`  Value: ${JSON.stringify(flag.value)}`);
      console.log(`  Metadata:`, flag.metadata);
      console.log('');
    });

    return data;
  } catch (error) {
    console.error('❌ Error:', error.message);
    throw error;
  }
}

// Run the example
getFlags();

Run it:

node examples/get-flags.js