Introduction
This guide provides information on the Web SDK which enables you to:
- Develop web applications that can be deployed to the platform.
- Communicate authenticated with our API.
- Apply default or branded UI components to your custom application.
Web SDK for Angular JS is deprecated. Therefore, its documentation is no longer provided here. As all Cumulocity IoT REST APIs are backward compatible, Angular JS applications will still continue to work.
Web SDK for plugins is based on Angular JS and is also deprecated. For Angular-based development, we recommend you to implement native Angular modules. For more information, refer to the Tech Community.
When can I use the Web SDK?
The Web SDK is designed to extend default application or build new IoT solutions. It provides many default components to compose such applications. However, if one of our default applications already fits your usecase, you should think about extending it via the less-code approach and install plugins to them. If you simply have very special needs or can’t find the right plugin for you use-case, consider building a custom application with the help of the Web SDK. There you basically have three options:
- Extend existing applications.
- Build a new application with the help of the Web SDK.
- Build a application from scratch.
The third option is the hardest option as you need to build nearly everything new. However, you are free to choose your frameworks and tools. To support you on either of the options, we have developed and published certain packages to npm. Those packages help you to connect to our data, provides you with default components or help you test and deploy the app. Depending on your needs, you can decide which package you want to include. However we always encourage everyone to start with our boilerplates and the full Web SDK. You can find a description on how to use them in the Getting started guide.
Packages
The Web SDK consists of the following packages deployed to npm in the scope @c8y and available under Apache 2.0 license:
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>> (for example @c8y/cockpit) 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/style: The styles for the look and feel of an application. Extend this package to apply a custom branding to your application.
- @c8y/<<apps>>: The different applications. E.g.
@c8y/cockpit,@c8y/devicemanagementand@c8y/administraiton. - @c8y/websdk: The scaffolding package that you can use to add the Cumulocity applicaiton to your Angular application.
- @c8y/devkit: The builders to build or run a dev server.
@c8y/client: Accessing data
The @c8y/client is an isomorphic (node and browser) Javascript client library for the Cumulocity IoT REST API. It can be used for getting data from the platform. In an Angular application you will mostly use the injected services from @c8y/ngx-components.
@c8y/ngx-components: The component library
ngx-components is a components collection and data access layer for Angular applications. It allows you to access our platform from within an Angular application as well as to provide the core components. To achieve this, the ngx-components consists of two basic imports:
- core (
@c8y/ngx-components) which contains all core components like title, navigator or tabs. - api (
@c8y/ngx-components/api) which enables dependency injection of the @c8y/client services. - features (
@c8y/ngx-components/<<feature-name>>) a set of features that add functionality to an application
@c8y/style: Branding and theming
We recommend to use our build in branding editor to change the look and feel of all applications in one go. If you still want to change certain style options, the @c8y/style package contain all our .less based styling. You can extend this styling and build your own custom theme.
@c8y/<<apps>>: Extendable applications
The following table provides an overview on the current packages existing for applications. You can scaffold a new application from any of this applications and then change or extend it.
| Name | Description |
|---|---|
@c8y/application |
An empty application to quickly bootstrap new applications. It is the default application. |
@c8y/hybrid |
Also an empty application but running in hybrid mode. That means it can import angularjs plugins and therefore can be used for migration purposes. |
@c8y/tutorial |
An application that already assembles most of the concepts of the @c8y/ngx-components. Use this to get real code examples. |
@c8y/widget-plugin |
An Module Federation plugin that can be used to create your own custom widgets. |
@c8y/package-blueprint |
A blueprint (template) for an application which can be uploaded as a package and act as a starting point for a custom application. |
@c8y/cockpit |
The Cockpit default application. Use this to extend the existing Cockpit application. |
@c8y/devicemanagement |
The Device Management default application. Use this to extend the existing Device Management application. |
@c8y/administration |
The Administration default application. Use this to extend the existing Administration application. |
Build tooling: @c8y/websdk and @c8y/devkit
Additional two build tools are added, which help scaffolding (@c8y/websdk) and developing (@c8y/devkit) the application. The package @c8y/websdk is quite simple and only provides the promps for creating a new applicaiton. The overall havy lifting is done by the @c8y/devkit. It replaces the default dev-server and builder options in the angular.json and extends the webpack configuration with everything needed.
Versioning: The WebSDK uses semantic version numbers
Since version 1019.0.0 the versioning schema of the Web SDK isn’t aligned anymore to the versioning schema of the Cumulocity IoT platform. The versioning schema is now reflecting via semantic versioning the changes in the Web SDK:
- Major version (e.g. 1019.x.x): Can contain breaking changes. Updating to such versions needs proper testing and validation. Often those versions also contain an Angular upgrade.
- Minor version (e.g. x.3.x): Contains features that should work without breaking anything. However it is recommended to properly verify the feature a minor version contains.
- Fix version (e.g. x.x.7): Cotains only fixes that should not break anything.
We recommend to use the ^ or ~ in the package.json for all @c8y liberaries. When you are using a yealy long term support release, it is best to use the npm tag in your package.json. The long term support versions always end with -lts.
As our releases are bound to the Angular versioning, you must to ensure that you scaffold the right Angular version. Otherwise the scaffolding process will fail and give you a peer dependency error. The following table shows an overview of the supported versions:
| Angular version | Web SDK version | Comment |
|---|---|---|
| 16.x.x | 1019.x.x | Using Angular CLI tooling. |
| 15.x.x | 1018.1.x - 1018.x.x | Using c8ycli tooling, only yearly release |
| 14.x.x | 1016.x.x - 1018.0.x | Using c8ycli tooling |
1019.x.x you must to use our old tooling based on the c8ycli tool-set. For more information see C8Y Command Line Tool (CLI).Next steps
If you just want to get started, we recommend to read the next chapter which explains how you can setup your first Web SDK based Angular application. If you already have setup an application and want to understand more details of the concept, we recommend to jump to our Codex developer documentation which explains the concepts, list all the components and defines guidlines for the styling.