스크립트 작성과 JavaScript API

이 문서는 화면을 확인하고, 필요한 부분을 인식한 뒤 결과를 판단하는 순서로 JavaScript 스크립트를 작성하는 방법을 설명합니다. 먼저 장치 연결과 화면 미리보기를 확인하고, 스크립트 편집기에서 JavaScript를 선택하세요. 설치 버전에서 해당 언어를 선택할 수 없으면 실행하지 말고 버전과 오류를 확인하세요.

예제의 좌표·검색 이미지는 자신의 장치에 맞춰야 합니다. 이미지 검색 결과가 있다고 해서 자동 입력이 항상 원하는 동작을 한다는 뜻은 아닙니다. 처음에는 입력 없는 예제부터 실행하고, 입력을 시험할 때는 본인이 사용할 권한이 있는 테스트 화면에서 한 번만 확인하세요.

1. 입력 없이 화면 크기 확인

getScreenSize()는 [width, height] 배열을 반환합니다. 좌표를 정하기 전에 크기를 확인하세요. 예제는 결과를 로그에 남길 뿐 화면을 누르지 않습니다.

var size = getScreenSize();
if (size.length === 2 && size[0] > 0 && size[1] > 0) {
    log("화면 크기: " + size[0] + " x " + size[1]);
} else {
    log("화면 크기를 확인하지 못했습니다. 장치 연결을 확인하세요.");
}

0이거나 비어 있는 값이 나오면 장치 선택과 미리보기를 먼저 확인합니다. 화면 크기가 바뀌면 이전 좌표나 다른 해상도에서 만든 템플릿을 그대로 사용하지 마세요.

2. 템플릿 검색 결과 확인

장치의 현재 화면에서 만든 이미지 파일 경로를 지정합니다. 아래 button.png는 제공되는 파일이 아닌 자리표시자이므로 자신이 준비한 파일로 바꾸세요. 검색 결과는 객체이며 found로 성공 여부를 구분합니다. 객체 자체가 참인지 검사하면 미검출 결과도 성공으로 오인할 수 있습니다.

var result = matchTemplate("button.png", 0.8);
if (result.found) {
    log("검색 위치: " + result.x + ", " + result.y);
    log("매칭 점수: " + result.score);
} else {
    log("이미지를 찾지 못했습니다. 경로·해상도·화면 상태를 확인하세요.");
}

반환값의 x, y를 확인하세요. 기존 문서의 result.center[0] 형식과 다릅니다. 인식 점수는 해당 비교의 결과이며 모든 화면에서의 정확도 보장이 아닙니다. 임계값을 낮추기 전 템플릿과 실제 화면의 배율·테마·언어가 같은지 확인하세요.

3. 작은 영역의 글자 읽기

JavaScript의 OCR 영역은 배열이 아니라 {x, y, width, height} 객체입니다. 예제의 영역이 장치 화면 안에 들어가는지 확인하고 숫자를 수정하세요.

var text = ocrRead({x: 100, y: 200, width: 300, height: 50});
if (text.length > 0) {
    log("읽은 문자: " + text);
} else {
    log("문자를 읽지 못했습니다. 영역과 원본 캡처를 확인하세요.");
}

빈 문자열만으로 원인을 단정할 수 없습니다. 영역에 글자가 없는 경우, 글자가 잘린 경우, 연결·인식 상태에 문제가 있는 경우를 미리보기에서 구분하세요. 민감한 화면 내용을 로그에 남기지 않도록 주의하세요.

4. 범위를 확인한 뒤 한 번만 입력

다음 예제는 조건이 맞으면 실제 탭을 한 번 보냅니다. x, y는 의도한 테스트 위치로 수정하세요. 구매·삭제·계정 설정 화면에서는 시험하지 마세요. 실행 화면의 중지 기능을 먼저 확인하세요.

var size = getScreenSize();
var x = 100;
var y = 200;
if (size.length === 2 && x >= 0 && y >= 0 && x < size[0] && y < size[1]) {
    var sent = tap(x, y);
    log(sent ? "탭 요청을 보냈습니다. 실제 화면을 확인하세요." : "탭 요청에 실패했습니다.");
} else {
    log("좌표가 화면 범위 밖입니다. 입력하지 않았습니다.");
}

tap()의 참 반환값은 입력 요청 결과를 나타냅니다. 원하는 버튼이 눌렸는지 또는 작업이 완료됐는지는 실제 화면에서 별도로 확인해야 합니다. 반복문을 추가하기 전에 한 번의 결과와 종료 방법부터 확인하세요.

함수 이름과 반환값

JavaScript 함수 이름은 대소문자를 구분합니다. 아래는 위 예제에 사용한 함수와 관련 함수를 정리한 것입니다.

함수	반환값·용도
`getScreenSize()`	화면 크기 배열 `[width, height]`
`matchTemplate(path, threshold)`	`found`, 성공 시 `x`·`y`·`score`를 가진 객체. 기본 임계값 0.8
`waitTemplate(path, timeout, threshold)`	지정한 시간까지 검색. 같은 형식의 객체. 기본 시간 10초·임계값 0.8
`ocrRead(roi)`	인식한 문자열. 영역 객체는 `x, y, width, height`
`ocrFind(text, roi)`	`found`, 성공 시 `x`·`y`를 가진 객체
`tap(x, y)`	입력 요청 성공 여부. 실제 화면 결과는 별도 확인
`doubleTap(x, y, interval)`	두 번 탭. 기본 간격 50밀리초
`textInput(text)`	문자 입력 요청 성공 여부
`log(message, level)`	로그 기록. 기본 수준 `info`
`wait(seconds)`	대기. 초 단위를 사용

Python·Lua와 버전 차이

JavaScript 예제를 Python·Lua 편집기에 그대로 붙여 넣을 수 없습니다. 함수 이름뿐 아니라 객체와 배열, 반환값도 다를 수 있습니다. 이전 웹 문서의 모든 언어 예제가 현재 설치 버전에서 동일하게 실행된다고 확인된 것은 아닙니다. 여기서는 확인한 JavaScript 인터페이스에 맞춰 예제를 제공합니다.

다른 언어를 사용한다면 설치된 앱의 API 문서와 실제 실행 결과를 함께 확인하세요. Lua는 빌드의 런타임 포함 여부에 따라 사용할 수 없을 수 있습니다. Python에서 장치 제어 함수가 정의되지 않았다는 오류가 나면 함수가 지원되는지 확인해야 하며, JavaScript 예제를 Python 코드처럼 바꾼 것만으로 해결되지는 않습니다.

위 예제의 구문과 분기 로직은 시험했지만, 모든 배포 버전·장치에서 실제 입력 결과를 검증한 것은 아닙니다. 문제가 생기면 스크립트 오류 점검에 따라 설치 버전, 선택 언어, 오류 메시지와 최소 재현 예제를 정리하세요.