Overview

The Web SDK enables you

• to develop web applications that can be deployed to the platform,
• to communicate authenticated with our API,
• to apply default or branded UI components to your custom application.

The Web SDK consists of the following packages deployed to npm in the scope @c8y:

These packages depend on each other from top to bottom. While the @c8y/client is a very low-level API interface with nearly no dependencies, the @c8y/apps provide feature rich applications by including @c8y/ngx-components and @c8y/client.

The goal of these splittings is to provide the right package for every use case, e.g. if you want to build a small application with React you could use the @c8y/client to do the API interaction. If you need a brandable feature rich application which is close to our Cockpit or Device Mangement application you could use @c8y/ngx-components together with @c8y/stlyes.

Following is a list which explains the use cases of each package.

• @c8y/client: Use this client to access our API. The client is isomorphic, that means it could be used in node.js and in the browser.
• @c8y/ngx-components: A components collection and data access layer for Angular applications. This package can be used to build Angular applications.
• @c8y/styles: The styles for the look & feel of an application. Extend this package to apply a custom branding to your application.
• @c8y/apps: Example and bootstrapping applications to easily let you start with the Web SDK.

Next, we will showcase how to get started with our Web SDK CLI.

Getting started

First install the Command Line Interface (CLI) which helps you with bootstrapping an application:

$ npm install -g @c8y/cli

Next, bootstrap a new blank application with the new command:

$ c8ycli new myApp

Note: When you want to see the possibilities and implementation details of the Web SDK you should try the tutorial application. You can install it by running c8ycli new <<your-app-name>> tutorial.

Once the CLI installation is completed change to the newly created folder and run npm install:

$ cd myapp
$ npm install

After all packages are installed you can start the application by running:

$ npm start

If you point your browser to http://localhost:9000 you will get a login screen which proxies to the demo tenant as default backend. If you cannot log in, it might be pointing to the wrong backend. To change the proxy to your tenant URL change the start script in the script section of the newly created package.json:

{
  "start": "c8ycli server -u http://your-tenant.my-provider.com"
}

After logging in you should see a barely empty starter application. If you want to start with a more complex example read the documentation about @c8y/apps. If you want to build and deploy your application read more about the necessary commands of the @c8y/cli tool.

Info: Currently Web SDK only supports building new applications. If you want to extend an existing application like Cockpit or Dashboard, read the legacy documentation.

First route & component

After creating the empty bootstrapping application you might want to start with your first content. To do so, add a new component to your project and save it as hello.component.ts:

import { Component } from '@angular/core';

@Component({
  selector: 'app-hello',
  template: `
    <c8y-title>Hello World</c8y-title>
    <p>My first content.</p>
  `
})
export class HelloComponent {
  constructor() {}
}

To hook the new component into the application you need to declare the new component and add it to a route in the app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule } from '@angular/router';
import { CoreModule, BootstrapComponent, CommonModule} from '@c8y/ngx-components';
import { HelloComponent } from './hello.component'; // don't forget to import the new component

@NgModule({
  imports: [
    BrowserModule,
    RouterModule.forRoot([{ path: '', component: HelloComponent }], // hook the route here
    { enableTracing: false, useHash: true }),
    CoreModule,
    CommonModule
  ],
  declarations: [HelloComponent], // add deceleration here
  bootstrap: [BootstrapComponent]
})
export class AppModule {}

If you start this application and log in you will see an application similar to the following screenshot. To extend this application you can use the Angular Router in combination with our @c8y/ngx-components.