Skip to content

Latest commit

 

History

History

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

@rollgate/sdk-angular

CI npm version License: MIT

Official Angular SDK for Rollgate - Feature flags made simple.

Requirements

  • Angular 14+
  • RxJS 7+

Installation

npm install @rollgate/sdk-angular
# or
yarn add @rollgate/sdk-angular
# or
pnpm add @rollgate/sdk-angular

Quick Start

1. Import the Module

// app.module.ts
import { NgModule } from "@angular/core";
import { RollgateModule } from "@rollgate/sdk-angular";

@NgModule({
  imports: [
    RollgateModule.forRoot({
      apiKey: "your-api-key",
      // Optional: initial user for targeting
      user: {
        id: "user-123",
        email: "user@example.com",
        attributes: { plan: "pro" },
      },
    }),
  ],
})
export class AppModule {}

Standalone Components (Angular 17+)

// app.config.ts
import { ApplicationConfig } from "@angular/core";
import { ROLLGATE_CONFIG } from "@rollgate/sdk-angular";

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: ROLLGATE_CONFIG,
      useValue: {
        apiKey: "your-api-key",
      },
    },
  ],
};

2. Use in Components

// app.component.ts
import { Component } from "@angular/core";
import { RollgateService } from "@rollgate/sdk-angular";

@Component({
  selector: "app-root",
  template: `
    <div *ngIf="rollgate.isReady$ | async; else loading">
      <div *ngIf="rollgate.isEnabled('new-feature')">
        New feature is enabled!
      </div>
    </div>
    <ng-template #loading>Loading flags...</ng-template>
  `,
})
export class AppComponent {
  constructor(public rollgate: RollgateService) {}
}

Usage

RollgateService

Inject the service to check flags:

import { Component } from "@angular/core";
import { RollgateService } from "@rollgate/sdk-angular";

@Component({
  selector: "app-feature",
  template: `
    <div *ngIf="isNewFeatureEnabled">New Feature!</div>
    <div *ngIf="flags$ | async as flags">
      Premium: {{ flags["premium-feature"] }}
    </div>
  `,
})
export class FeatureComponent {
  isNewFeatureEnabled: boolean;
  flags$ = this.rollgate.flags$;

  constructor(private rollgate: RollgateService) {
    this.isNewFeatureEnabled = this.rollgate.isEnabled("new-feature");
  }

  async onLogin(user: User) {
    await this.rollgate.identify({
      id: user.id,
      email: user.email,
      attributes: { plan: user.plan },
    });
  }

  async onLogout() {
    await this.rollgate.reset();
  }
}

Reactive Flag Observable

import { Component } from "@angular/core";
import { Observable } from "rxjs";
import { RollgateService } from "@rollgate/sdk-angular";

@Component({
  selector: "app-feature",
  template: `
    <div *ngIf="showBanner$ | async">
      <app-banner />
    </div>
  `,
})
export class FeatureComponent {
  showBanner$: Observable<boolean>;

  constructor(private rollgate: RollgateService) {
    this.showBanner$ = this.rollgate.getFlag$("show-banner");
  }
}

FeatureDirective

Structural directive for conditional rendering:

<!-- Basic usage -->
<div *rollgateFeature="'new-feature'">New feature is enabled!</div>

<!-- With else template -->
<ng-template
  [rollgateFeature]="'premium-feature'"
  [rollgateFeatureElse]="freeTpl"
>
  Premium content
</ng-template>
<ng-template #freeTpl>Free content</ng-template>

Configuration

RollgateModule.forRoot({
  // Required
  apiKey: "your-api-key",

  // Optional
  baseUrl: "https://api.rollgate.io",
  refreshInterval: 30000, // Polling interval (ms)
  enableStreaming: false, // Use SSE for real-time updates
  timeout: 5000, // Request timeout (ms)

  // Initial user context
  user: {
    id: "user-123",
    email: "user@example.com",
    attributes: { plan: "pro" },
  },

  // Retry configuration
  retry: {
    maxRetries: 3,
    baseDelayMs: 100,
    maxDelayMs: 10000,
    jitterFactor: 0.1,
  },

  // Circuit breaker configuration
  circuitBreaker: {
    failureThreshold: 5,
    recoveryTimeout: 30000,
    monitoringWindow: 60000,
    successThreshold: 3,
  },

  // Cache configuration
  cache: {
    ttl: 300000, // 5 minutes
    staleTtl: 3600000, // 1 hour
  },
});

Event Tracking

Track conversion events for A/B testing:

import { Component, OnDestroy } from "@angular/core";
import { RollgateService } from "@rollgate/sdk-angular";

@Component({
  selector: "app-checkout",
  template: `<button (click)="handlePurchase()">Buy Now</button>`,
})
export class CheckoutComponent implements OnDestroy {
  constructor(private rollgate: RollgateService) {}

  handlePurchase() {
    this.rollgate.track({
      flagKey: "checkout-redesign",
      eventName: "purchase",
      userId: "user-123",
      value: 29.99,
    });
  }

  // Flush pending events on destroy (auto-flushes every 30s)
  ngOnDestroy() {
    this.rollgate.flush();
  }
}

TrackEventOptions

Field Type Required Description
flagKey string Yes The flag key this event is associated with
eventName string Yes Event name (e.g., 'purchase', 'signup')
userId string Yes User ID
variationId string No Variation ID the user was exposed to
value number No Numeric value (e.g., revenue amount)
metadata Record<string, unknown> No Optional metadata

API Reference

RollgateService

Property/Method Description
flags$ Observable of all flags
isReady$ Observable of ready state
isLoading$ Observable of loading state
isError$ Observable of error state
isStale$ Observable of stale state
circuitState$ Observable of circuit breaker state
isEnabled(flagKey, default?) Check if flag is enabled
isEnabledDetail(flagKey, default?) Flag value with evaluation reason
flags Get all flags synchronously
isLoading Get loading state synchronously
isError Get error state synchronously
isStale Get stale state synchronously
circuitState Get circuit breaker state synchronously
isReady Get ready state synchronously
identify(user) Set user context
reset() Clear user context
refresh() Force refresh flags
getMetrics() Get SDK metrics snapshot
track(options) Track a conversion event (A/B testing)
flush() Flush pending events to the server

FeatureDirective

<!-- Basic usage -->
<div *rollgateFeature="'feature-name'">Content</div>

<!-- With else template -->
<ng-template
  [rollgateFeature]="'feature-name'"
  [rollgateFeatureElse]="fallback"
>
  Feature enabled
</ng-template>
<ng-template #fallback>Feature disabled</ng-template>

Documentation

Full documentation: rollgate.io/docs

About Rollgate

Rollgate is a feature management platform that helps teams release features safely with gradual rollouts, user targeting, and instant kill switches.

License

MIT