4.지원기능 및 사용예제

Edit

4.1지원기능

4.1.117.1 이후 버전 사용 시 주의 사항

LauncherService 1.1.0.17 미만 버전 사용 시 globalvalue 속성값을 처리하지 못하는 오류가 있습니다. 배포 페이지에서 LauncherService 버전을 확인하고 1.1.0.17 이상 버전으로 업데이트할 수 있도록 가이드해야 합니다.

// 런처서비스 버전 정보 체크
function checkUpdateLauncher() {
    if (xhrObject.readyState == 4 || xhrObject.reqType == 2) {
        if (xhrObject.status == 200 || xhrObject.reqType == 2 && launcher_response(xhrObject.responseText)) {
 
            //1. getlauncherversion 런처서비스 버전 정보
            var resultJson = JSON.parse(xhrObject.responseText);
            strLocLuncherVer = resultJson.value["getlauncherversion"].productversion;
 
            //2. 설치 되어 있는 버전 보다 상위 값이면 TPL_LauncherDownload() 호출
            if (strLauncherVersion > strLocLuncherVer) {
                TPL_LauncherDownload("update");
            } else {
                //nexacro 실행..
            }
        }
    }
}
 
// 배포 페이지에서 메세지 셋팅 후 download_TPLSvc() 호출
function TPL_LauncherDownload(str) {
    var msg = "설치 되지 않았습니다.";
    if (str == "update") { msg = "업데이트 되었습니다."; }
    var contents = "TPLSvc가 " + msg + " TPLSvc를 다운로드 후 설치를 진행해 주시기 바랍니다.";
 
    var divCon = document.getElementById("errorDiv")
    divCon.innerHTML = "<H3>" + contents + "</H3>";
    document.location = download_TPLSvc("newlanucher");
}
 
var strLauncherFileName = "TPLSvc_Setup.exe";
 
// 런처서비스 다운로드 
function download_TPLSvc(type) {
    if (type == "newlanucher") {
        // 서버 경로의 TPLSvc_Setup.exe 다운로드
        var downURL = strServerPath + strDownloadPath + "/" + strLauncherFileName;
        return downURL;
    }
}

4.1.2속성

Property

default

Data Type

설명

key

없음

string

필수속성입니다.

서비스의 Key값을 설정

동일 start.json 상의 유일한 값이어야 함

bjson

없음

string

필수속성입니다.

서비스의 start.json 경로를 지정

globalvalue

없음

string

넥사크로플랫폼 Engine이 구동될 때 globalvariable에 추가될 변수를 설정

splashimage

없음

string

넥사크로플랫폼 Engine이 Loading되는 동안 보여줄 스플래시 이미지 경로를 지정

지정하지 않을 경우 넥사크로플랫폼 기본이미지가 출력되며, 이미지는 화면의 중앙에 표시됨

onlyone

false

boolean

key와 bjson 값에 매칭되는 Instance를 하나만 띄울 것인지에 대한 여부를 설정

screenid

없음

string

앱이 실행되는 Screen ID를 설정

enginesetupkey

없음

string

필수속성입니다.

실행경로로 사용할 특정 버전의 넥사크로플랫폼 ProductKey 값을 지정.

사이트에서 별도 작성한 Setup Module을 사용하는 경우, 이 Property에 Setup을 만들 때 부여되는 Product Key를 설정함. 설정하지 않을 경우 서비스가 제대로 동작하지 않을 수 있음

setupresource


boolean

SetupResource.zip 파일을 내려받는 기능의 사용 여부를 설정

1.1.0.9 이후 버전부터 지원

componentpath


string

컴포넌트가 저장될 경로를 설정

loadingimage


string

화면, 데이터 로딩 시 표시되는 이미지를 설정

splashmessage


string

splashimage 사용 시 메시지 출력 여부 설정

'none' 또는 ''(빈 값) 설정 시 메시지를 출력하지 않음

속성값에 특수문자가 포함된 경우 예기치 못한 결과가 발생할 수 있습니다.

key, bjson 속성값에 세미콜론(;) 또는 ".Run" 문자열이 포함된 경우 보안상 문제가 될 수 있어 해당 문자열을 삭제하여 처리합니다 (1.1.0.12 이후 버전부터 적용됩니다).

key, bjson 속성값에 콤마(,), TAB 문자(\t), 개행(\n, \r) 또는 ". Run" 처럼 점(.)과 "run" 문자열 사이의 공백문자가 포함된 경우 보안상 문제가 될 수 있어 해당 문자열을 삭제하여 처리합니다 (1.1.0.16 이후 버전부터 적용됩니다).

splashimage 속성에 다음 확장자를 가진 파일은 지정할 수 없습니다 (1.1.0.16 이후 버전부터 적용됩니다).

bat, bin, cmd, com, cpl, exe, gadget, inf1, ins, inx, isu, job, jse, lnk, msc, msi, msp, mst, paf, pif, ps1, reg, rgs, scr, sct, shb, shs, u3p, vb, vbe, vbs, vbscript, js, ws, wsf, wsh, dll, hta

componentPath 속성 설정 시 아래와 같은 제약이 있습니다 (1.1.0.23 이후 버전부터 적용됩니다).

  • 허용된 alias만 사용해서 값을 설정할 수 있습니다.

  • 경로에 ".."을 포함해 상위 폴더를 지정할 수 없습니다.

4.1.3메소드

Method

Result

Parameter

Description

launch

없음

없음

넥사크로플랫폼 Engine을 NRE로 실행시킴.

makeshortcut

없음

strShortCutName

strIconPath

strIconTargetPath

strPosition

bAllUser

단축아이콘을 생성함.

- strShortCutName:바로가기 아이콘명

- strIconPath: 바로가기 아이콘 파일을 내려받을 수 있는 서버 경로

- strIconTargetPath: 바로가기 아이콘을 내려받은 로컬 경로 (alias 허용)

- strPosition: 바로가기 생성위치

"startmenu"/ "startup" / "programs" / "desktop" 중 택일함

잘못된 값이 들어오면 "desktop"으로 처리함

- bAllUser :전체 사용자가 사용할 수 있도록 생성할지에 대한 여부(default는 false)

isexistshortcut

boolean

strShortcutName

strPosition

bAllUser

입력받은 인자에 해당하는 바로가기 아이콘이 존재하는지 확인.

- strShortCutName:바로가기 아이콘명

- strPosition: 바로가기 생성위치

"startmenu"/ "startup" / "programs" / "desktop" 중 택일함

잘못된 값이 들어오면 "desktop"으로 처리함

- bAllUser :전체 사용자가 사용할 수 있도록 생성할지에 대한 여부(default는 false)

getengineversion

string

strEngineKeyName

시스템에 설치된 엔진 키에 해당하는 엔진 설치 버전을 가져옴.

strEngineKeyName: Engine Setup Key

download

없음


앱 실행 시 사용되는 자원을 다운로드.

deleteshortcut

boolean

strShortcutName

strPosition

bAllUser

바로가기 아이콘을 삭제.

- strShortCutName:바로가기 아이콘명

- strPosition: 바로가기 생성위치

"startmenu"/ "startup" / "programs" / "desktop" 중 택일함

잘못된 값이 들어오면 "desktop"으로 처리함

- bAllUser :전체 사용자가 사용할 수 있도록 생성할지에 대한 여부(default는 false)

addWebInfo

없음

strCookie

현재 브라우저의 쿠키정보를 자동으로 globalvariable의 cookie변수에 추가.

strCookie: 브라우저의 쿠키정보

downloadresource


param

SetupResource.zip 파일이 위치한 서버 경로를 지정

1.1.0.9 이후 버전부터 지원

메소드 파라미터값에 특수문자가 포함된 경우 예기치 못한 결과가 발생할 수 있습니다.

makeshortcut 메소드 실행 시 문자열로 전달되는 파라미터값에 세미콜론(;) 또는 ".Run" 문자열이 포함된 경우 보안상 문제가 될 수 있어 해당 문자열을 삭제하여 처리합니다 (1.1.0.15 이후 버전부터 적용됩니다).

makeshortcut, deleteshortcut, isexistshortcut 메소드 실행 시 문자열로 전달되는 파라미터값(strShortCutName)에 세미콜론(;), 콤마(,), TAB 문자(\t), 개행(\n, \r) 또는 ". Run" 처럼 점(.)과 "run" 문자열 사이의 공백문자가 포함된 경우 보안상 문제가 될 수 있어 해당 문자열을 삭제하여 처리합니다 (1.1.0.16 이후 버전부터 적용됩니다).

4.1.4이벤트

Event

parameter

Occurs

error

nError

strMsg

런처 서비스 실행 중에 에러가 발생하면 세팅되는 이벤트

- nError: 에러코드

- strMsg: 에러 메시지

Error Code

Error Message

Description

102

Not exist key. Please input key.

key 값을 설정하지 않은 경우

103

Not exist bootstrap.Please input bootstrap.

bjson 값을 설정하지 않은 경우

104

Fail to download.

이미지 파일을 내려받을 수 없는 경우

105

Fail to load config file.

nexacro.xml 파일을 읽을 수 없는 경우

106

Fail to write config file.

nexacro.xml 파일을 기록할 수 없는 경우

4.1.5참고

디지털 서명을 유지한 상태로 설치 파일을 배포

SetupRuntime.exe 설치 파일을 실행하기 전에 SetupResource.zip 파일을 사용자 PC에 먼저 내려받아야 합니다.

디지털 서명을 유지한 상태로 설치 파일을 배포하는 방식은 런처서비스 버전 1.1.0.9 이후 버전부터 지원합니다.

setupresource 속성 설정

런처 서비스 구동을 위한 setproperty 함수에서 setupresource 속성값을 아래와 같이 true로 설정합니다.

objNexacro.action = 'setproperty';
if (action_sub == 'basic') {
    objNexacro.value = {
        "key": strKey,
        "bjson": strBjson,
        "splashimage": strSplashImage,
        "componentpath": strComponentPath,
        "loadingimage": strLoadingImage,
        "globalvalue": strGlobalValue,
        "onlyone": bOnlyone,
        "splashmessage": 'none',
        "setupresource": 'true',
        "enginesetupkey": strEnginesetupKey
    };
}

downloadresource 메소드 설정

start.json, SetupResource.zip 파일이 위치한 서버 경로를 인자값으로 설정합니다. downloadresource 메소드가 실행되면 설정된 경로에서 SetupResource.zip 파일을 "%USERAPP%SetupResource"경로에 내려받습니다.

else if (action == 'downloadresource') {
    objNexacro.value = {
        "downloadresource": {
            "param": ["http://127.0.0.1:8080/test/"]
        }
    };

downloadresource 메소드 실행 이후에 SetupRuntime.exe 파일을 내려받는 스크립트가 동작하도록 합니다.

4.2사용예제

런처 실행 스크립트를 어떻게 구현하는지 간략한 예제를 설명합니다. 예제는 자바스크립트로 구현되었으며 사용하는 환경에 맞게 수정해 사용할 수 있습니다.

아래 예제는 구글 크롬 브라우저에서 넥사크로플랫폼 앱이 동작하는 예제입니다. IE 브라우저에서 동작하는 예제는 전체 코드를 참조해주세요.

4.2.1신규 id 요청

platform, action 요소 항목값을 채우고 신규 id를 요청합니다.

function start()
{
    objNexacro.platform = 'nexacro';
    objNexacro.action = 'create';
    sendData(true, true, createProcess);
}

function sendData(openpost, is_create, resultCallback) 
{
    delete xhrCreateObject;
    xhrCreateObject = null; 
    
    var sendObj = null;
    sendObj = new XMLHttpRequest();
    sendObj.reqType = 1;

    xhrCreateObject = sendObj;
    sendObj.onreadystatechange = resultCallback;
    var jsonData;
    jsonData = JSON.stringify(objNexacro);
    var timestamp = "/" + new Date().getTime();
    var send_url = openurl + ":" + openport + openurl_add + timestamp;
    console.log(send_url);

    sendObj.open("POST", send_url, "true");
    sendObj.send(jsonData);
    console.log(jsonData);    
    return sendObj;
}

function createProcess()
{
    if ( xhrCreateObject.readyState == 4 || xhrCreateObject.reqType == 2)  {
        console.log(xhrCreateObject.responseText);
    }          
}

요청되는 jsonDate 항목은 아래와 같습니다. 요소 항목만 채워서 전송됩니다.

{"platform":"nexacro","action":"create"}

런처 서비스에서 요청을 받고 id를 할당해 반환합니다. id 항목과 result 항목을 확인합니다. id값은 이후 요청 시 활용하게 됩니다.

{"action":"create","id":"1522821857","platform":"nexacro","result":"success"}

4.2.2필수 속성 설정

예제에서 [property setting(basic)] 버튼 클릭 시 동작하는 기능입니다. 속성 중에서 key, bjson, enginesetupkey 항목값을 채웁니다.

function do_property(test_action, action_sub)
{
    objNexacro.action = 'setproperty';
    objNexacro.value = { "key": "LauncherService", "bjson": "http://127.0.0.1:8080/start.json", "enginesetupkey":enginesetupkey};
    sendData(true, false, resultProcess);
}

넥사크로플랫폼 앱 배포 시 Local 설정으로 배포한 경우에는 start.json 경로를 로컬 주소로 지정해야 합니다. 이런 경우에는 아래와 같이 지정합니다.

function do_property(test_action, action_sub)
{
    objNexacro.action = 'setproperty';
    objNexacro.value = { "key": "LauncherService", "bjson": "D:\\nexacro\\17\\start.json", "enginesetupkey":enginesetupkey};
    sendData(true, false, resultProcess);
}

요청되는 jsonDate 항목은 아래와 같습니다. 이전 단계에서 확인된 id값을 설정하고 key, bjson, enginesetupkey 항목값이 채워져 있습니다.

{"action":"setproperty","id":"1522822903","platform":"nexacro","result":null,"value":{"key":"LauncherService","bjson":"http://127.0.0.1:8080/start.json","enginesetupkey":"{94FAAFF5-0E54-4539-AA67-*******}"}

런처 서비스에서 필수 속성값을 저장하고 성공 여부("result":"success")를 반환합니다.

{"action":"setproperty","id":"1522823068","platform":"nexacro","result":"success","value":{"bjson":"http://127.0.0.1:8080/start.json","enginesetupkey":"{94FAAFF5-0E54-4539-AA67-*******}","key":"LauncherService"}}

4.2.3메소드 실행

예제에서 [launch] 버튼 클릭 시 동작하는 기능입니다.

function do_method(test_action) {
    objNexacro.action = 'method';
    objNexacro.value = {"launch": null};
    sendData(true, false, resultProcess);
}

이전 단계에서 key, bjson, enginesetupkey 항목값을 전송했고 런처 서비스에서 해당하는 값을 저장하고 있습니다. id값을 키값으로 값을 저장하고 있기 때문에 이후 메소드를 실행하거나 다른 동작을 할때는 id값을 기준으로 동작하게 됩니다.

{"action":"method","id":"1522823068","platform":"nexacro","result":null,"value":{"launch":null}}

런처 서비스에서 메소드를 실행하고 성공 여부("result":"success")를 반환합니다. 정상적으로 메소드가 실행되었다면 운영체제에 설치된 앱이 실행됩니다.

{"action":"method","id":"1522823068","platform":"nexacro","result":"success","value":{"launch":null}}

4.2.4전체 코드

아래 링크에서 사용 예제 코드를 내려받을 수 있습니다.

localtest_nexacro_sample.html

예제 코드 내에는 아래와 같은 문제 처리 방법이 포함되어 있습니다.

if (window.XMLHttpRequest) {
    sendObj = new XMLHttpRequest();
    sendObj.reqType = 1;
} else if (window.XDomainRequest) {
    sendObj = new XDomainRequest();
    sendObj.reqType = 2; 
}
function http_onerror()
{
    if (objNexacro.action == 'create') {
        if (findport == false) {
            if ( setport > 0) {
                setport = 0;
                openport = parseInt(getCookie("tplsvcopenport"), 10) | 0;
                if (openport > 0) {
                    sendData(true, true, createProcess);
                    return;
                }
            }
            openport = 7895;
        } else {
            openport++;
        }
        findport = true;
                
        if (openport <= 7935) //신규 런처는 7895 ~ 7935 사이 하나의 port를 open 함; 
            sendData(true, true, createProcess);
        else
            alert("런처 서비스가 설치되지 않았거나 동작이 멈춰있는지 확인 바랍니다.");          
    }     
}