The global header is available as web component and as an angular library. The web component can be used in any web application. The angular library is intended for apps using angular 15 or higher. Angular apps below angular 15 should either upgrade to angular 15 or use the web component. Note however that the web component causes material menus (<mat-menu>) to not work properly in angular apps.
There are 3 project stages
Install the library with npm/yarn (or download it from here):
yarn add @vi/global-header
add the following to your NgModule
import { GlobalHeaderModule } from '@vi/global-header';
@NgModule({
declarations: [...],
imports: [
...
GlobalHeaderModule.forRoot({
// (environment.ts)
baseUrl: 'https://api-integration.viessmann.com',
accountAppUrl: 'https://account-integration.viessmann.com'
})
],
providers: [...]
})
export class MyModule
Add following code to your index.html header:
<head>
...
<script defer src="https://global-header-integration.viessmann.com/elements.js"></script>
<link rel="stylesheet" type="text/css" href="https://global-header-integration.viessmann.com/styles.css">
...
</head>
In Angular apps using the web component you need to add following code to the regarding module (this is NOT required if you use the angular library):
schemas: [CUSTOM_ELEMENTS_SCHEMA]
@NgModule({
declarations: [],
imports: [],
schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class SomeModule {}
Regardless of whether you are using the web component or the angular library, you can now just add the components into your html template:
<vih-support-link></vih-support-link>
<vih-app-switcher></vih-app-switcher>
Set the attributes "login-redirect-url" and / or "logout-redirect-url" to redirect the user to given URL after login / logout.
<vih-login login-redirect-url="https://allowed.redirect.url/dashboard" logout-redirect-url="https://allowed.redirect.url/public" ></vih-login>
This component fires an event on logout named logoutEvent
.
You can use it for custom coding on your side (e.g. clearing Local Storage).
By default, after successful login, users are redirected to the origin URL they came from. You can
change this by specifying a different loginRedirectUrl
. For example if the (publicly
available) landing page of your application is http://my-app.com/
and your app has a
dashboard you can configure this URL to redirect users to that page after login.
GlobalHeaderModule.forRoot({
...
loginRedirectUrl: 'http://my-app.com/dashboard'
})
After logout the user is redirected to the exact URL where the logout button was pressed. So if your app
is divided into public and protected sections (e.g. some pages require login and some not) you may want
to always redirect to a public page. Otherwise, if the user clicks logout from a page that is protected
by e.g. an angular route guard that automatically redirects to IAM, a login would be triggered right
after logout. To set the redirect URL after logout to a different url, add
logoutRedirectUrl
to global header configuration. It can be either set to
true
or to the target URL.
GlobalHeaderModule.forRoot({
...
logoutRedirectUrl: 'http://my-app.com/public'
})
Set the attribute "type" to "endcustomer" to apply some EK-specific adjustments (default: "customer"). In endcustomer mode, a different registration link is used and the "forgot username" link, which is only available for customers, is hidden.
<vih-login type="endcustomer"></vih-login>
GlobalHeaderModule.forRoot({
...
type: 'endcustomer'
})
<vih-bell></vih-bell>
Depending on your application's overall style, the global header might not look like on this sample
page. For example, the icons or texts in the menus might have different color. The global header
components intentionally do not enforce them, to allow customization for app-specific style. You can
easily override the styles (classes app-switcher
and app-login
) to adapt them
to your app's look-and-feel:
#my-header .app-switcher .mat-icon {
color: white;
}
#my-header .app-login .mat-icon {
color: white;
}
For angular apps: If your application has its own "logged in" state, e.g. if your app detects the
session has timed out, you can set appManagesAuthentication
and use the Observable input
param authenticated
of login component. It will subscribe to the Observable and update the
loggedIn state when the value is changed, without making calls to the platform.
<vih-login [appManagesAuthentication]="true" [authenticated]="my.loggedInState$"></vih-login>
The components display all texts in the user's browser language (Accept-Language
header) by
default, supporting the following languages:
Language-only string is coerced to the best matching language+country string (e.g. 'de' -> 'de-DE'). If
your app has a language selector, you can use the parameter lang
for each component, e.g.
<vih-login lang='fr-FR'></vih-login>
<vih-app-switcher lang='fr-FR'></vih-app-switcher>
For apps like avendoo which can't authenticate against everest, you can still use the app switcher by
setting the user-id
param:
<vih-app-switcher user-id="userId"></vih-app-switcher>
Some users disable third party cookies and some browsers even started blocking them by default which produces problems for our cookie-based SAML authentication. To get around this, apps should use CSRF token approach as described here. You can set the appId of your application in Global Header either via configuration (angular apps only)
GlobalHeaderModule.forRoot({
...
appId: 'myAppId'
})
or via component input
<vih-login app-id="myAppId"></vih-login>
(works for both angular and non-angular apps).
After successful login, the redirect URL will contain the CSRF token as described on the wiki page mentioned above.
If your application performs login itself, you can also pass it via parameter `csrfToken` to both components. The parameter can be either the token itself or the name of the local storage key that holds the token:
<vih-login csrf-token="token or key"></vih-login>
<vih-app-switcher csrf-token="token or key"></vih-app-switcher>
By default the IAM login page has a login form on the left side and an empty entire right side. By adding an optional global header configuration parameter `iamBackgroundImage` you can specify a background image which fills that empty space on the right.
GlobalHeaderModule.forRoot({
...
iamBackgroundImage: 'iam_lpi_000001.png' // or other image file which is supported by IAM
})
If you see a neverending spinning circle (loading) animation where the login / app switcher components should be, this can have multiple reasons:
/users/me
endpoint returns a 401 error, so if you have a global error interceptor, this
will most likely lead to problems.