Angular SDK Integration

The official ConfigBee SDK for Angular applications provides a seamless way to integrate feature flags and dynamic configurations into your Angular projects. With ngx-configbee, you can easily manage dynamic configurations and feature flags in real-time without requiring application redeployments.

Installation

Install the SDK via npm or yarn:

npm
yarn

npm install ngx-configbee

yarn add ngx-configbee

Setup

SDK Initialization

You have two ways to initialize the SDK depending on your Angular application structure:

For Angular Applications with AppModule

Add the ConfigBee service to your application’s root module:

import { NgModule } from '@angular/core';
import { NgxConfigbeeService } from 'ngx-configbee';

@NgModule({
  // Your module declarations, imports, etc.
})
export class AppModule {
  constructor(cb: NgxConfigbeeService) {
    cb.init({
      accountId: 'your-account-id',
      projectId: 'your-project-id',
      environmentId: 'your-environment-id'
    });
  }
}

For Standalone Angular Applications

Initialize the SDK in your entry point file (e.g., main.ts or app.config.ts):

import { APP_INITIALIZER } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { NgxConfigbeeService } from 'ngx-configbee';

function initializeConfigBee(cb: NgxConfigbeeService): () => Promise<any> {
  return () => cb.init({
    accountId: 'your-account-id',
    projectId: 'your-project-id',
    environmentId: 'your-environment-id'
  });
}

platformBrowserDynamic([
  {
    provide: APP_INITIALIZER,
    useFactory: initializeConfigBee,
    deps: [NgxConfigbeeService],
    multi: true
  }
]).bootstrapModule(AppModule)
  .catch(err => console.error(err));

Using the SDK

Inject the Service

Inject NgxConfigbeeService into your components or services:

import { Component } from '@angular/core';
import { NgxConfigbeeService } from 'ngx-configbee';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  constructor(protected cb: NgxConfigbeeService) {}
}

Access Configurations in Templates

Access feature flags and configurations directly in your component templates:

<!-- Show loading state -->
<div *ngIf="cb.isLoading">
  Loading configurations...
</div>

<!-- Access configurations when ready -->
<div *ngIf="cb.isActive">
  <h3>Feature Flags</h3>
  <p>Multilingual Enabled: {{cb.flags.multilingualEnabled ? 'Yes' : 'No'}}</p>

  <h3>Dynamic Configurations</h3>
  <p>Sidebar Size: {{cb.numbers.sideBarSize}}px</p>
  <p>Top Bar Text: {{cb.texts.topBarText}}</p>

  <h3>JSON Configurations</h3>
  <p>Active Versions: {{cb.jsons.updateConfig.active_versions}}</p>
</div>

React to Configuration Updates

For components using OnPush change detection, subscribe to updates:

import { Component, ChangeDetectionStrategy, ChangeDetectorRef, OnInit, OnDestroy } from '@angular/core';
import { NgxConfigbeeService } from 'ngx-configbee';
import { Subscription } from 'rxjs';

@Component({
  selector: 'app-feature',
  templateUrl: './feature.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class FeatureComponent implements OnInit, OnDestroy {
  private subscription: Subscription;

  constructor(
    protected cb: NgxConfigbeeService,
    private cd: ChangeDetectorRef
  ) {}

  ngOnInit() {
    this.subscription = this.cb.updates.subscribe(event => {
      // Trigger change detection when configurations update
      this.cd.markForCheck();
    });
  }

  ngOnDestroy() {
    if (this.subscription) {
      this.subscription.unsubscribe();
    }
  }
}

Key Naming Conventions

ConfigBee SDK automatically normalizes keys to follow JavaScript variable naming conventions:

Original key in ConfigBee: multilingual.enabled
Normalized key for usage: multilingualEnabled

You can disable this behavior by setting normalizeKeys: false during initialization.

Targeting

ConfigBee supports user targeting to deliver different configurations based on specific criteria. This is especially useful for personalized experiences or gradual rollouts.

Setting Target Properties

You can set target properties in two ways:

During Initialization

cb.init({
  accountId: 'your-account-id',
  projectId: 'your-project-id',
  environmentId: 'your-environment-id',
  targetProperties: {
    "userId": "user-123",
    "userRole": "admin"
  }
});

After Initialization

// Set or update target properties
cb.setTargetProperties({
  "userId": "user-123",
  "userRole": "admin",
  "region": "us-west"
});

// Clear all target properties
cb.unsetTargetProperties();

Example: User Login/Logout Flow

@Component({
  selector: 'app-auth',
  template: `...`
})
export class AuthComponent {
  constructor(private cb: NgxConfigbeeService) {}

  onLoginSuccess(user) {
    // Set user-specific targeting
    this.cb.setTargetProperties({
      "userId": user.id,
      "userName": user.name,
      "userRole": user.role
    });
  }

  onLogout() {
    // Clear targeting when user logs out
    this.cb.unsetTargetProperties();
  }
}

API Reference

Methods

Method	Description
`init({ accountId, projectId, environmentId, normalizeKeys?, targetProperties? })`	Initializes the ConfigBee service
`setTargetProperties(targetProperties: {[key: string]: string})`	Sets or updates target properties
`unsetTargetProperties()`	Clears all target properties

Getters

Getter	Type	Description
`isActive`	`boolean`	Indicates if the ConfigBee service is active
`isLoading`	`boolean`	Indicates if the service is loading data
`isTargetingActive`	`boolean`	Indicates if targeting is active
`isTargetingLoading`	`boolean`	Indicates if targeting is loading
`status`	`string`	Current service status: “INITIALIZING”, “ACTIVE”, “DEACTIVE”, or “ERROR”
`targetingStatus`	`string`	Current targeting status
`flags`	`object`	Contains all feature flags (boolean values)
`texts`	`object`	Contains all text configurations
`numbers`	`object`	Contains all numeric configurations
`jsons`	`object`	Contains all JSON configurations
`updates`	`Observable`	Emits events when configurations change

Best Practices

Initialize Early: Initialize the SDK as early as possible in your application lifecycle.
Error Handling: Always handle the loading state with isLoading and provide fallback values.

Default Values: Establish default values for configurations in case they’re not yet loaded:

get sidebarWidth(): number {
  return this.cb.isActive ? this.cb.numbers.sidebarWidth : 250;
}