본문으로 건너뛰기

공통 매개변수와 반환 객체

이 페이지에서는 LCC.assist API 그룹이 공통으로 사용하는 options, 작업 객체, 결과 객체 및 오류 상태를 설명합니다.

options 필드​

필드유형기본값설명
typestring"text"요청 유형입니다. "text"/"text-reply", "point"/"pick-point", "control"/"device-control"을 모두 인식합니다. 편의 래퍼가 자동으로 설정합니다.
titlestring"脚本请求人工辅助"중앙 제어 서버 측 카드 제목입니다. 이 기본값은 SDK에 고정된 중국어 간체 문자열입니다.
text / promptstring""작업자에게 표시할 설명입니다. “추가 정보” 같은 표현이 아니라 구체적인 작업을 작성해야 합니다.
timeoutnumber300대기 시간(초)입니다. 작업을 만들 때 백엔드 만료 시간으로도 사용합니다.
pollIntervalMsnumber1000폴링 간격(밀리초)입니다. 250보다 작으면 250으로 처리합니다.
screenshotLocalPathstring장치의 로컬 스크린샷 파일입니다. SDK가 중앙 제어 서버의 files/_temp/assist/lua-script/<udid>/<request-id>/...에 업로드합니다.
screenshotPathstring중앙 제어 서버의 files 루트 디렉터리에 이미 있는 이미지의 상대 경로입니다.
screenshotImage / imageImageObjectXXTouch 이미지 객체입니다. SDK가 data URL로 내보내 input.imageSrc에 기록합니다.
screenshotImageData / imageDatastringPNG/JPEG 이미지 바이너리 데이터입니다. SDK가 data URL로 변환해 input.imageSrc에 기록합니다.
screenshotImageFormat / imageFormatstring"jpeg"screenshotImage의 내보내기 형식으로, "jpeg" 또는 "png"를 선택할 수 있습니다.
screenshotImageQuality / imageQualitynumber0.7screenshotImage를 JPEG로 내보낼 때의 품질이며, 범위는 0.0~1.0입니다.
screenshotImageMimeType / imageMimeTypestring자동 인식screenshotImageData의 MIME 유형입니다. PNG/JPEG 데이터에는 일반적으로 전달할 필요가 없습니다.
imageRecttable잘린 이미지를 장치 좌표로 다시 매핑할 때 사용합니다. 예: { left = 100, top = 200, width = 300, height = 120 }.
inputtable{}추가 구조화 정보로, 중앙 제어 서버 측에 그대로 전달됩니다. SDK가 requestType과 scriptRequestId를 추가합니다.

screenshotLocalPath는 screenshotPath보다 우선합니다. 이번 요청에 screenshotLocalPath를 전달하면 SDK가 파일을 업로드하고 업로드된 경로를 사용합니다.

input.imageSrc와 screenshotLocalPath / screenshotPath를 모두 전달하지 않은 경우 SDK가 screenshotImage 또는 screenshotImageData를 input.imageSrc로 변환하려고 시도합니다. ImageObject는 호출자가 관리하며 SDK는 자동으로 destroy()하지 않습니다.

ImageObject 직접 전달​

local img = screen.image()
local result, err = LCC.assist.request_control({
    title = "수동 처리 필요",
    text = "원격 제어로 현재 검증을 완료한 뒤 완료를 클릭해 주세요",
    screenshotImage = img,
    screenshotImageQuality = 0.6,
})
if img.destroy then
    img:destroy()
end

이미지 데이터 직접 전달​

local img = screen.image()
local data = img:png_data()
if img.destroy then
    img:destroy()
end

local result, err = LCC.assist.request_control({
    title = "수동 처리 필요",
    text = "원격 제어로 현재 검증을 완료한 뒤 완료를 클릭해 주세요",
    screenshotImageData = data,
})

이미지 주소 직접 전달​

local result, err = LCC.assist.request_control({
    title = "수동 처리 필요",
    text = "원격 제어로 현재 검증을 완료한 뒤 완료를 클릭해 주세요",
    input = {
        imageSrc = "data:image/jpeg;base64,...",
    },
})

input.imageSrc는 파일을 업로드하지 않으며 screenshotPath에도 기록되지 않습니다.

메모리를 장시간 점유하지 않도록 작업이 제출·취소·만료 상태가 되면 중앙 제어 서버가 작업의 input에서 imageSrc를 제거합니다. 요청을 처리하는 동안에는 이미지가 계속 정상적으로 표시됩니다.

작업 객체​

task는 중앙 제어 서버 측에 저장되는 지원 작업이며, 자주 사용하는 필드는 다음과 같습니다.

{
    id = "assist_xxx",
    kind = "text-reply",
    title = "인증 코드 입력",
    prompt = "스크린샷을 확인하고 인증 코드를 입력해 주세요",
    status = "pending",
    deviceId = "장치 UDID",
    source = "lua-script",
    screenshotPath = "assist/...",
    input = {},
    result = nil,
    createdAt = 1781196058792,
    updatedAt = 1781196058792,
    expiresAt = 1781196358792,
}

시간 필드는 밀리초 타임스탬프입니다. 스크립트가 만든 요청에는 deviceId = device.udid()와 source = "lua-script"가 자동으로 기록됩니다.

결과 객체​

텍스트 답변에 성공한 경우:

{ kind = "text-reply", text = "1234" }

좌표 선택에 성공한 경우:

{
    kind = "pick-point",
    x = 123,
    y = 456,
    imageX = 123,
    imageY = 456,
    color = "AABBCC",
}

x와 y는 장치의 물리 좌표이므로 touch.tap에 바로 사용할 수 있습니다. imageX와 imageY는 스크린샷 내부 좌표입니다.

수동 원격 제어에서 “완료”를 클릭한 경우:

{ kind = "device-control", completed = true }

수동 원격 제어에서 “결과 수동 제출”을 펼쳐 유효한 JSON을 제출하면 result는 해당 JSON에 대응하는 Lua 값입니다. 예를 들어 다음을 제출하면:

{"allowed":true,"reason":"수동 확인"}

스크립트는 다음을 받습니다:

{ allowed = true, reason = "수동 확인" }

수동 원격 제어에서 JSON이 아닌 일반 텍스트를 직접 제출한 경우:

{ note = "일반 텍스트 내용" }

빈 내용을 수동으로 제출하면 작업이 제출되지 않고 스크립트가 계속 기다립니다.

오류 및 상태​

대기에 실패하면 다음을 반환합니다:

nil, err, task

일반적인 err:

  • "cancelled": 사용자 또는 스크립트가 취소했습니다.
  • "expired": 백엔드 작업이 만료되었습니다.
  • "timeout": 스크립트 대기 시간이 초과되었으며 SDK가 작업 취소를 시도했습니다.
  • "not found": 작업이 없습니다. 백엔드가 다시 시작되었거나 작업이 정리되었을 수 있습니다.
  • 기타 문자열: 네트워크, 스크린샷 업로드 또는 백엔드 API가 반환한 오류 텍스트입니다.

submitted 상태에서만 result를 반환합니다. cancelled, expired, timeout은 모두 수동 결과를 받지 못한 것으로 처리해야 합니다.