API Document

NOTE: MagiCloud Widget SDK Version 2 is obsolete. You can migrate to version 3 (obsolete) 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. Initialize MagiCloud Widget SDK based to your needs and MagiCloud Resources are available for your web site.

Prerequisites

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 provide page url where script will be used (also called returnUri) which will be set as trusted at our authentication server and binded to your applicationId.
Your web site must use HTTPS protocol because of restricted resources and sensitive login information.
Include babel-polyfill to your application. See documentation https://babeljs.io/docs/usage/polyfill/. If used in Browser then follow documentation https://babeljs.io/docs/usage/polyfill/#usage-in-browser. You can use CDN library from https://cdnjs.com/libraries/babel-polyfill. Babel-polyfill 6.26.6 has been added in Installing section example.

Installing

Include script to bottom of body

<script src="https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/6.26.0/polyfill.min.js"></script>
<script src="https://sdk.magicloud.com/magicloud.min.js"></script>

Implement business logic

MagiCloud.load({
    applicationId: 'YOUR_APPLICATION_ID',  // enter given applicationId here for restricted resources
    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;
    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. ApplicationId is provided against to ReturnUri.

Page behind ReturnUri is needed to return authentication values for authentication logic where logic will pick those values for later usage. You can also customize that page to indicate for user that authentication is going on e.g. progress bar or spinner. Otherwise page will flash short time before logic has been picked authentication values.

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

Authentication methods

// Login user
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(function(response {
    var userId = response.Id;
    var userFullname = response.Fullname;
    // update UI e.g. show download links and show logout button
});

// Automatically signin user if user have valid cookie
MagiCloud.autoSignIn().then(function (response) {
    // Authentication succeed
}, function (response) {
    // Authentication didn't succeed
});

// Logout user
MagiCloud.logout().then(function() {
    // update UI e.g. hide download links and show login button
});

// You can toggle your UI with this value
var isLogged = MagiCloud.isLoggedIn();

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({
    applicationId: 'YOUR_APPLICATION_ID',
    productId: 'YOUR_PRODUCT_ID'
}).then(function(data) {    
    if(MagiCloud.isLoggedIn()) {        
        $("#btnDownloadDxf").attr("href", data.DxfUrl); // DXF link is valid
        var attachments = data.Attachments; // RFA links are valid and could be populated
    }
    else {
        // Implement logic to login if user has not been logged in
        $("#btnDownloadDxf").text("Login is required to download DXF file");
    }
}

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 autoSignIn method to automatically sign in user (if cookie exists). 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);

MagiCloud Widget SDK Version 2