NgxZendeskWebWidget

Angular wrapper for the Zendesk Web Widget v1 (classic). Inspired by AlisonVilela/ngx-zendesk-webwidget, a library that seems to not be maintained anymore.

Install

npm install @halloverden/ngx-zendesk-web-widget --save

Usage

Config and Init

To configure the library, you should extend the provided config class NgxZendeskWebWidgetConfig, and then import the library module's forRoot method, passing your config, like so:

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    AppRoutingModule,
    NgxZendeskWebWidgetModule.forRoot(ZendeskConfig)
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

Synchronous Init

The package comes with a factory function that you can use if you want to initialize the Web Widget when your own application initializes. To do so, add the following provider to your AppModule.

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    AppRoutingModule,
    NgxZendeskWebWidgetModule.forRoot(ZendeskConfig)
  ],
  providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: ngxZendeskWebWidgetFactory,
      deps: [NgxZendeskWebWidgetService],
      multi: true
    }
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

Asynchronous Init

If you want to lazy load the Web Widget, for example when waiting for cookie consent, you can create your own service and inject the NgxZendeskWebWidgetService to it. Then, when you're ready, simply run the init method of the NgxZendeskWebWidgetService.

@Injectable({
  providedIn: 'root'
})
export class MySuperService {
  constructor(private ngxZendeskWebWidgetService: NgxZendeskWebWidgetService) {}

  methodThatRunsWhenReady() {
    this.ngxZendeskWebWidgetService.init();
  }
}

API

Config

accountUrl: string

The url for your Zendesk account. Usually <your-sub-domain>.zendesk.com.

callback(ngxZendeskWebWidgetService: NgxZendeskWebWidgetService): any

This callback method runs after init.

injectionTag: keyof HTMLElementTagNameMap | string

The name of the tag that you want to inject the iframe element into (the one that loads the initial JavaScript snippet from Zendesk).

lazyLoadZendeskScripts: boolean

Whether to lazy load the widget.

timeout: number

How long (in milliseconds) to wait for external scripts to load.

zESettings?: NgxZendeskWebWidgetZeSettingsInterface

An object representing the settings that can be used to configure to the widget itself.

Factory

Use this when you want to initialize the widget synchronously.

Service

The NgxZendeskWebWidgetService has a couple of utility methods worth knowing about.

init()

Used to initialize the Web Widget. Returns Promise<boolean>. Resolves to true when initialization has completed.

isInitialized()

Indicates whether the widget is initialized.

zE()

Returns the zE instance.

commandWebWidget(command: string, options?: any)

Helper method for running commands.

onWebWidgetEvent(eventName: string, handler: (event?: any) => void)

Helper method for subscribing to events.

Interfaces

There are two interfaces in the package. They represent the zE instance and the settings that can be set in the config class. Please refer to the Web Widget API Reference for more information. Also, should you find any errors, please open an issue.

Issues

Report issues here

License

MIT © Hallo Verden

Changelog

Changelog can be found here

Contribute

PRs are welcome.

Development server

You can run this project locally, but it also comes with a Docker image to avoid any 'works on my machine' situations.

Using Docker

Navigate to the docker folder, and copy the .env.example file to .env. Tweak any of the variables to your needs (see the docker-compose.yaml file for how they're used). Run docker-compose build, then docker-compose up -d. Enter the container with docker-compose exec angular /bin/bash. You're now at the root of the project inside the container. Follow the Running locally section from here, but use the port you set in the .env file.

Running locally

Run ng serve to serve the sample-test-app project. Navigate to http://localhost:4200/. The application will automatically reload if you change any of the source files.

Config

Update the zendesk.config.ts file in the sample-test-app project with settings relevant to you.

Build

Run ng build to build the project. The build artifacts will be stored in the dist/ directory.

Running unit tests

Run ng test to execute the unit tests via Karma.