Home Reference Source Repository

MagiCloud Widget SDK Version 4.0.0.296

MagiCloud Widget SDK offers simple access to MagiCloud Resources.

Getting Started

Just include MagiCloud Widget SDK to your web site. Initialize MagiCloud Widget SDK based to your needs and MagiCloud Resources are available for your web site.

If you have been already done implementation with earlier version then you should look migration guide to update your implementation.

Prerequisites

  1. Contact to MagiCloud Team and get your own client_id. Some of MagiCloud resources e.g. RFA/DXF downloads need authentication. Using restricted resources you need to host provided html page (later called popup_redirect_uri) which will be set as trusted at our authentication server and binded to your client_id.

  2. Your web site must use HTTPS protocol because of restricted resources and sensitive login information.

Installing

Include script to bottom of body

<script src="https://sdk.magicloud.com/v4/magicloud-widget-sdk.min.js"></script>

Initialize

You need to call init function to initialize MagiCloud Widget SDK library.

MagiCloud.init({
    client_id: 'YOUR_CLIENT_ID',           
    popup_redirect_uri: 'TRUSTED_REDIRECT_URI',

    // Authenticated user status events
    onLoadUser: function (user) {
        // Event handler to get signed in user if any exists
        // e.g. case when page refreshed
    },
    onSignin: function (user) {
        // Event handler to perform some action on user signin
    },
    onSignout: function () {
        // Event handler to perform some action on user signout
    },

    // Product data load events
    onLoad: function(data) {
        // Event handler to perform some action on product data load
    },
    onLoadError: function(err) {
        // Event handler to perform some action on error when product data loaded
    },

    // X3D rendering
    onRenderX3D: function() {
        // Event handler to perform some action after succesful x3d rendering
    }
});

Implement business logic

MagiCloud.init({
    ...
    onLoad: onLoad,
    onLoadError: onLoadError
    ...
});

MagiCloud.load({
    productId: 'YOUR_PRODUCT_ID'    
});

// Set to onLoad property on init method
function onLoad(data) {
    var productCode = data.ProductCode;
    var dxfDownloadUrl = data.DxfUrl;
    var attachments = data.Attachments; // contains e.g. RFA files
    var image2D = data.ImageUrl;
    var dimensionImage = data.DimensionsUrl;

    var options = {
        containerId: 'YOUR_3D_CONTAINER_ID',
        x3dUri: data.X3DUrl,
        imageUri: data.ImageUrl
    };
    MagiCloud.renderX3D(options);

    var variantInfo = data.VariantDetails; // If any variants
    var variantCount = data.VariantDetails.VariantCount;
    // NOTE: Remember add pagingSize query to get amount of needed variants otherwise top 10 will be listed
    var moreVariantInfoUrl = data.VariantDetails.VariantDetailsUrl + "?pagingSize=" + data.VariantDetails.VariantCount;

    // Get response from moreVariantInfoUrl and use is similar than above e.g. response.ImageUrl
    // Example:
    $.get(moreVariantInfoUrl).then(function (response) {
        $.each(response, function (index, item) {
            $.get(item.DetailsUrl).then(function (itemResponse) {
                var variantImageUrl = itemResponse.ImageUrl;
            });
        });
    });

    // update UI
    ...
}

// Set to onLoadError property on init method
function onLoadError(err) {
    // Handle error situation....
}

Authentication

MagiCloud Authentication requires client_id specified by MagiCloud team. The client_id is provided against to the popup_redirect_uri where you need to host login callback html file for finalization of performed authentication action. We will provide minimum content of the callback html file. You can customize that html page to indicate for user that some authentication action is going on e.g. progress bar or spinner but it is not required. After successful authentication all restricted resource urls will contain needed information to download resouce e.g. token, applicationId and sessionId.

Callback HTML file

It is required to host callback html file in same domain where MagiCloud Widget SDK is used to complete authentication action e.g. login action.

NOTE: This html file will be seen awhile when authentication action is performed. You can create some custom styles for this page if wanted. Following example contains simple spinner.

Example content of callback html file. This file is required to be available on popup_redirect_uri:

<!DOCTYPE html>
<html>

<head>
    <link rel="stylesheet" type="text/css" href="https://sdk.magicloud.com/v4/callbacks/loader.css">
</head>

<body>
    <div class="loader"></div>
    <script src="https://sdk.magicloud.com/v4/callbacks/oidc-client.min.js"></script>
    <script src="https://sdk.magicloud.com/v4/callbacks/signin-popup-callback.js"></script>
</body>

</html>
Signin
// Use signin when user signin needed
MagiCloud.signin();
Signout
// Use signout when user signout needed
MagiCloud.signout();
Get authenticated user status

You can set event handlers during initialization of the MagiCloud Widget SDK library:

MagiCloud.init({
    client_id: 'YOUR_CLIENT_ID',           
    popup_redirect_uri: 'TRUSTED_REDIRECT_URI',
    onLoadUser: function (user) {
        console.log($`user {user.username} is signed in.`);
    },
    onSignin: function (user) {
        console.log($`user {user.username} signed in.`);
    },
    onSignout: function () {
        console.log('user is signed out!');
    },
    ...
});
How to access restricted resources?

DXF and RFA downloads are restricted resources. Before showing download links in UI you need to check is user logged in. If user is logged in then product data contain needed information to get restricted resources. Otherwise resources cannot be downloaded.

// Set to onLoad property on init method
function onLoad(data) {        
    // If user is authenticated these links will contain needed parameters to download content
    // Otherwise links can be only used to determine available downloads
    var dxf = data.DxfUrl; // DXF link
    var attachments = data.Attachments; // RFA links
}
How to maintain authentication status in UI?

You can handle authenticated user status on UI by using onLoadUser, onSignin and onSignout event setters.

Disclaimer: This is just example and you might need to implement your own business logic for authentication

MagiCloud.init({
    client_id: 'YOUR_CLIENT_ID',           
    popup_redirect_uri: 'TRUSTED_REDIRECT_URI',

    onLoadUser: function (user) {
        console.log($`user {user.username} is signed in.`);
    },
    onSignin: function (user) {
        console.log($`user {user.username} signed in.`);
    },
    onSignout: function () {
        console.log('user is signed out!');
    },
    ...
});

updateUI();
updateDimensionsX3D();

function updateUserInfo(user) {
    if (user) {
        $("#login").hide();
        $("#logout").show();
        $("#username").text(user.username);
    } else {
        $("#logout").hide();
        $("#login").show();
        $("#username").empty();
    }
    updateUI();
}

$("#login").click(function () {
    MagiCloud.signin();
});
$("#logout").click(function () {
    MagiCloud.signout();
});

Features

Features introduced below require load method call to get product data.

How to use diagrams?

You need to specify diagram image and data image containers with wanted diagram type Currently supported diagrams:

{ Ventilation, Heating, Cooling, SupplyAir, ExtractAir, Radiator, Pump }

Diagrams available for current product can be read from Diagrams property Example of Diagrams property:

{ "Ventilation": { "BaseUrl": "https://.../api/diagram/abc/Ventilation", "HasData": true } }

Usage:

$.each(data.Diagrams, function (diagramType, item) {
    if (item.HasData) {
        // When user clicks element with id `diagramImageContainer-${diagramType}` 
        // then diagram data will appear to element with id `diagramDataImageContainer-${diagramType}`
        MagiCloud.setDiagram(data, { 
            type: diagramType, 
            elementId: `diagramImageContainer-${diagramType}`, 
            dataElementId: `diagramDataImageContainer-${diagramType}` 
        });

        // You can also operate with operation point values (valueXAxis/valueYAxis) if you have those already:
        // MagiCloud.setDiagram(data, 
        // { type: diagramType, 
        //   elementId: `diagramImageContainer-${diagramType}`, 
        //   dataElementId: `diagramDataImageContainer-${diagramType}`, 
        //   operationPoint: { x: valueXAxis, y: valueYAxis}
        // });
    }
    else {
        // Render diagram to element with id `diagramImageContainer-${diagramType}`
        MagiCloud.setDiagram(data, { type: diagramType, elementId: `diagramImageContainer-${diagramType}` });
    }
});

Advanced operations

2D, 3D and dimension images by QModelId and QModelParameters

QModel values can be used to create 2D, 3D and dimension images and this method doesn't require load method at all i.e. you can instantly call below methods to get needed resources without load method call.

var options = {
    containerId: 'x3dContainer',
    QModelId: qmodelId,                    // QModelId to customize X3D image
    QModelParameters: qmodelParameter,    // QModelParameters used to customize X3D image        
    ViewMode: 1                         // ViewMode: [0=Rendered, 1=DimensionLabels, 2=DimensionValues],
    ViewPosition: 1                     // ViewPosition: [0=Default, 1=Front, 2=Right, 3=Left, 4=Top, 5=Bottom, 6=IsometricLeft, 7=IsometricRight]
}
// Note: Second parameter. First time rendering x3d image pass false and always on update pass true
MagiCloud.renderX3D(options, update);

var alternativeImageUrl = MagiCloud.getImageQueryUrl(options);
var alternativeDimensionImageUrl = MagiCloud.getDimensionImageQueryUrl(options);
AHU Calculations

Get pressure drop of curve at specific flow. SystemTypeId value could be one of these:

{Unknown, AnyFluid, SupplyFluid, ReturnFluid, ColdWater, HotWater, FireHydrant, HotSupplyFluid, Sprinkler, Sewer, AnyAir, SupplyAir, ExtractAir, OutdoorSupply, OutdoorExhau}

Example:

let specifiedFlow_qV = 40.0;
let fanSpeed = 5;
let pressureDrop_dpTot = 30.0;
let systemTypeId = 'SupplyAir';

MagiCloud.getDpTot(data.Id, systemTypeId, specifiedFlow_qV, fanSpeed)
    .then(function(response) {
        // example of response: {Succeed: true, Value: 27.870676}
    });

Find suitable fanSpeed for given operation point. In example data.Id is product identifier (GUID) and systemTypeId is SupplyAir:

MagiCloud.findOptimalSpeed(data.Id, systemTypeId, specifiedFlow_qV, pressureDrop_dpTot)
    .then(function(response) {
        // example of response: {PressureDrop: 107.4791, Succeed: true, Value: 6}
    });

NOTE: You can also set callback functions on init function call e.g.

MagiCloud.init({
    ...
    onGetDpTot: function(response) { ... },
    onFindOptimalSpeed: function(response) { ... },
    ...
});

Migration Guide from 2.x to 4.x

Introduction

Prerequisites

Include script to bottom of body

Replace

<script src="https://sdk.magicloud.com/magicloud.min.js"></script>

With

<script src="https://sdk.magicloud.com/v4/magicloud-widget-sdk.min.js"></script>

Initialize

You need to call init function to initialize MagiCloud Widget SDK library. Without init function call MagiCloud Widget SDK cannot be used.

MagiCloud.init({
    client_id: 'YOUR_CLIENT_ID',           
    popup_redirect_uri: 'TRUSTED_REDIRECT_URI',

    // Authenticated user status events
    onLoadUser: function (user) {
        // Event handler to get signed in user if any exists
        // e.g. case when page refreshed
    },
    onSignin: function (user) {
        // Event handler to perform some action on user signin
    },
    onSignout: function () {
        // Event handler to perform some action on user signout
    },

    // Product data load events
    onLoad: function(data) {
        // Event handler to perform some action on product data load
    },
    onLoadError: function(err) {
        // Event handler to perform some action on error when product data loaded
    },

    // X3D rendering
    onRenderX3D: function() {
        // Event handler to perform some action after succesful x3d rendering
    }
});

Authentication

Properties applicationId and returnUri are deprecated and will be automatically mapped to new properties:

It is recommended to use client_id and popup_redirect_uri properties instead of obsolete properties.

MagiCloud.init({
    // applicationId: 'YOUR_APPID', // Use client_id instead. Property applicationId is deprecated and will be mapped to client_id.
    // returnUri: 'YOUR_RETURNURI', // Use popup_redirect_uri instead. Property returnUri is deprecated and will be mapped to popup_redirect_uri.
    client_id: 'YOUR_CLIENTID',
    popup_redirect_uri: 'YOUR_REDIRECT_URI' // callback html file
})

It is now required to host callback html file in same domain where MagiCloud Widget SDK is used to complete authentication action e.g. login action.

Minimum content of callback html file is required to be available on popup_redirect_uri. You can create your custom styles for this page:

<!DOCTYPE html>
<html>

<body>
    <script src="https://sdk.magicloud.com/v4/callbacks/oidc-client.min.js"></script>
    <script src="https://sdk.magicloud.com/v4/callbacks/signin-popup-callback.js"></script>
</body>

</html>

MagiCloud team will set your popup_redirect_uri as trusted url and after that authentication will work.

Now signin and signout functions are simplified to take no parameters:

MagiCloud.signin();
MagiCloud.signout();

Load method

You can now introduce onLoad, onLoadError, onRenderX3D, onGetDpTot and onFindOptimalSpeed functions on MagiCloud.init(options) function call by giving those in options object.

MagiCloud.init({
   ...
   onLoad: function(data) { ... },
   onLoadError: function(err) { ... },
   onRenderX3D: function() { ... },
   onGetDpTot: function() { ... },
   onFindOptimalSpeed: function() { ... },
   ...
});

MagiCloud.load({
    // applicationId: 'YOUR_APPID', // applicationId is not used anymore in load method so it can be removed
    productId: 'SOMETHING',
    logoContainerId: 'SOMETHINGELSEHERE',
});

Obsolete methods and properties

Authenticated user can be checked now with event handlers:

MagiCloud.init({
    ...
    onLoadUser: function (user) {
        console.log($`user {user.username} is signed in.`);
    },
    onSignin: function (user) {
        console.log($`user {user.username} signed in.`);
    },
    onSignout: function () {
        console.log('user is signed out!');
    },
    ...
});

© Progman Ltd. All rights reserved