Home Reference Source Repository

MagiCloud Widget SDK Version 3.0.0.288

NOTE: MagiCloud Widget SDK Version 3.0.0.288 is obsolete. You can migrate version 2.x to version 3.x with little effort. However it is recommended to use version 4 which has support and receives updates

MagiCloud Widget SDK offers simple access to MagiCloud Resources.

Getting Started

Just include MagiCloud Widget SDK to your web site and host one callback file on your 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 applicationId. Some of MagiCloud resources e.g. RFA/DXF downloads need authentication. Using restricted resources you need to host provided callback html page (later called returnUri) which will be set as trusted at our authentication server and binded to your applicationId.

  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/v3/magicloud-widget-sdk.min.js"></script>

Implement business logic

MagiCloud.load({
    productId: 'YOUR_PRODUCT_ID'    
}).then(function(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
    ...
}

Authentication

MagiCloud Authentication requires applicationId specified by MagiCloud team. The applicationId is provided against to the returnUri 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.

Sequency Diagram of Authentication Process

Login
// Login user
MagiCloud.login({        
    applicationId: 'YOUR_APPLICATION_ID', // enter given applicationId here for restricted resources
    returnUri: 'TRUSTED_REDIRECT_URI'
}).then(function(response {
    var username = response.username;
    // update UI e.g. show download links and show logout button
});
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.

Minimum content of callback html file is required to be available on returnUri:

<!DOCTYPE html>
<html>

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

</html>
Logout
// Logout user
MagiCloud.logout().then(function() {
    // update UI e.g. hide download links and show login button
});
Get authenticated user
// You can check is current user authenticated and toggle your UI with this value:
let isLoggedIn = MagiCloud.isLoggedIn();

// and you can try automatically signin user if user have valid cookie
MagiCloud.autoSignIn().then(function (response) {
    console.log(user.username);
}, function (response) {
    // Not authenticated
});
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.

MagiCloud.load({
    productId: 'YOUR_PRODUCT_ID'
}).then(function(data) {        
    // If user is authenticated these links will contain needed parameters to download content
    var dxf = data.DxfUrl; // DXF link
    var attachments = data.Attachments; // RFA links
}
How to maintain authentication status in UI?

You can use authentication methods introduced previously to maintain authentication status in UI. When initiating UI you can use getUser() method to automatically sign in user. It is also good to watch sign in status and trigger event if any changes to authentication status occurs.

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

autoSignIn();
watchSigninStatus();

function autoSignIn() {
    var that = this;
    MagiCloud.autoSignIn().then(function (response) {
        that.isLoggedIn = MagiCloud.isLoggedIn();
        setUserInfo(response);
    }, function (response) {
        setUserInfo();
    });
}

function setUserInfo(response) {
    if (MagiCloud.isLoggedIn() && response) {
        $("#btnLogin").hide();
        $("#btnLogout").show();
        $("#lblUsername").text(response.Fullname);
    } else {
        $("#btnLogout").hide();
        $("#btnLogin").show();
        $("#lblUsername").empty();
    }
    // Update UI
}

function watchSigninStatus() {
    var that = this;
    setTimeout(function () {
        if (that.isLoggedIn !== MagiCloud.isLoggedIn()) {
            autoSignIn();
        }
        // continue polling
        watchSigninStatus();
    }, 5000);
}

$("#btnLogin").click(function () {
    MagiCloud.login({
        applicationId: 'YOUR_APPLICATION_ID', // enter given applicationId here for restricted resources
        returnUri: 'TRUSTED_RETURN_URI' // We provide applicationId against your return uri
    }).then(setUserInfo);
});

$("#btnLogout").click(function () {
    MagiCloud.logout().then(setUserInfo);
});

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).then(function() {
    console.log("x3d updated")
});

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}
});

Migration Guide from 2.x to 3.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/v3/magicloud-widget-sdk.min.js"></script>

Login method

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 returnUri:

<!DOCTYPE html>
<html>

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

</html>

Load method

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

© Progman Ltd. All rights reserved