타입스크립트 API 예제는 Capacitor 및 Capgo

모든 __CAPGO_KEEP_0__ TypeScript API 예제 Capacitor의 모든 Capacitor은 다음과 같이 시작합니다: 유형이 지정된 플러그인 인터페이스입니다. 메서드, 옵션 및 Promise 결과를 명시적으로 지정하고, 웹 code 및 네이티브层는 하나의 계약을 공유하며, TypeScript는 실제로 이를 강제합니다.

강력하게 타입화된 Capacitor 플러그인 인터페이스를 구축하세요

The interface describes the API your web code sees. The native implementation behind it has to honor that contract — and TypeScript checks method names, parameters, and return values before your app ever runs.

import { registerPlugin } from ‘@capacitor/core’;

export interface DeviceStatus { 온라인: boolean; 배터리 수준?: number; }

export interface DevicePlugin { getStatus(): Promise; setLabel(options: { label: string }): Promise<{ saved: boolean }>;

export const Device = registerPlugin(‘Device’);

('Device');

이 몇 줄에는 많은 일이 진행되고 있습니다: explicit return type
결과를 예측할 수 있도록 합니다. 타입화된 options 객체
컴파일 시점에 누락된 속성이나 잘못된 속성을 잡을 수 있습니다. Promise 기반 메소드
일반적인 registerPlugin 제네릭 함수 호출 웹 API과 네이티브 브리지 사이를 연결하는 건 바로 이것이다.
인터페이스 인터페이스는 계약을 문서화할 뿐 runtime code에 추가적인 바이트를 추가하지 않는다.

모든 호출 사이트는 동일한 처리를 받는다:

const status = await Device.getStatus(); console.log(status.online);

await Device.setLabel({ label: '제작' });

Swap { label: 'Production' } for { name: 'Production' } 그리고 컴파일러는 즉시 이를 표시한다. 이는 모바일 릴리스 후에 발견하는 것보다 훨씬 낫다.

인터페이스는 또한 옵션 값을 모델링하고 실패 사례를 모델링한다. 네이티브 메서드가 항상 배터리 읽기를 제공할 수 없다면 batteryLevel?: number 모든 호출자에게 undefined.

아래의 다이어그램은 타입화된 메서드, 옵션, 반환 값, 브리지 정의 및 컴파일 타임 체크가 Capacitor 내부에서 어떻게 연결되는지 보여준다. API.

A TypeScript 플러그인 인터페이스에 대한 강력한 타입의 다이어그램을 보여주는 이미지.

핵심 아이디어: 타입 정의는 웹 인터페이스에서 native 플랫폼 로직 쪽으로 흐르며, 컴파일 타임 체크는 모든 호출 사이트에서 경계를 지킵니다.__CAPGO_KEEP_0__ 디자인에 대한 빠른 조회

API 디자인 빠른 참조

목적	예시	메소드 서명
호출 가능한 동작을 정의합니다.	옵션 타입	`getStatus()`
입력 형태를 제어합니다.	__CAPGO_KEEP_0__	`{ label: string }`
Promise 결과	비동기 작업을 나타내는 것	`Promise<DeviceStatus>`
결과 인터페이스	반환된 데이터를 정의하는 것	`online: boolean`

더 깊은 참조를 원한다면 TypeScript에서 API를 구축하는 방법에 대한 안내서를 읽어보세요 TypeScript에서 API를 구축하는 방법에 대한 안내서. 두 가지 좋은 습관을 유지하세요: 클라이언트에서 code을 제외한 비밀과 서명 인증서를 제거하고, 인터페이스를 각 플랫폼 구현에 테스트하기 전에 배포하기 전에.

모바일 팀은 JavaScript, 네이티브 code, 장치 권한, 비동기 플랫폼 서비스를 동시에 다루는 중입니다. 강력한 TypeScript 계약 각 경계에서 code이 iOS 또는 Android 장치에 도착하기 전에 기대치를 명확하게 하여, 각 경계에서 공유된 체크리스트처럼 작동합니다.

데스크 위에 커피 머그기 옆에 code을 표시하는 노트북 위에 앉아 있는 사람.

실제적인 TypeScript API 예시, __CAPGO_KEEP_0__를 비교하는 방법 Promise<DeviceStatus> 이러한 방법은 하나의 손으로 반환하는 __CAPGO_KEEP_0__ 데이터를 반환합니다. 유형이 지정된 버전은 편집기와 모든 리뷰어에게 존재하는 field가 정확히 어떤 field인지 알려줍니다. 유형이 지정되지 않은 버전은 runtime 로그, 수동 테스트, 최악의 경우 프로덕션 사고에 이러한 발견 작업을 밀어넣습니다.

수용 신호

TypeScript는 프론트 엔드의 한계를 벗어났습니다. 2024년 __CAPGO_KEEP_0__ 개발자 35%가 사용하고 있습니다. 2017년 __CAPGO_KEEP_0__ 개발자 12%에서 __CAPGO_KEEP_0__ 개발자 1,000만 명이 __CAPGO_KEEP_0__를 주 언어로 사용했습니다.2025년 __CAPGO_KEEP_0__ 개발자 1,000만 명이 __CAPGO_KEEP_0__를 주 언어로 사용했습니다. 12% in 2017__CAPGO_KEEP_0__ contributors GitHub __CAPGO_KEEP_0__ __CAPGO_KEEP_0__ 만약 raw 숫자를 원한다면.

모바일 조직에서 실제로 중요한 것은 그 궤적이다. 채용, 온보딩, 그리고 code 리뷰는 점점 더 공유된 타입에 의해 결정된다. 어떤 Capacitor 프로젝트에 참여하는 사람도 인터페이스를 읽고 예상되는 원시 동작을 이해할 수 있다. 그 동작을 구현하는 모든 구현을 추적하지 않아도 된다.

타입화된 API는 릴리스 작업을 더 쉽게 이해할 수 있게 한다. 특정 옵션 객체를 요구하는 메서드는 컴파일 시간에 이름이 변경된 속성이나 누락된 필드가 실패한다. 그 대신 반드시 형성된 원시 요청을 생성하지 않는다.

강력한 타입은 중요한 피드백을 왼쪽으로 이동시킨다.수정에 몇 분이 걸리면 대응할 수 있는緊急修정 릴리스가 필요하지 않다.

Capacitor 팀의 이익

크로스 플랫폼 앱은 일반적으로 여러 원시 구현 위에 있는 하나의 웹 대면 API을 노출한다. TypeScript는 모든 원시 세부 사항이 동일하게 행동하는지 증명할 수는 없지만 애플리케이션 전체에서 호출을 일관되게 유지할 수 있다.

explicit 타입을 적용하라:

메서드 입력, 필요한 옵션과 선택적 옵션 포함
Promise 결과, 성공 데이터가 항상 예측 가능한 형태를 갖도록 하라
이벤트와 리스너, 콜백이 알려진 페이로드를 처리한다.
에러 및 상태 값, fallback 경로가 표시되도록 하기 위해

이 구조는 장치 플러그인 또는 운영 서비스와 통합할 때 유용하다. 또한 잘못된 채널, 번들 식별자 또는 호환성 필드가 큰 사용자 기반에 영향을 미칠 수 있으므로 업데이트의 자동화에 팀이 리뷰하는 데 도움이 된다.

관련 패턴에 더 깊게 들어가려면 OpenAPI를 사용하여 생성된 타입화된 API에 대한. It covers how shared definitions reduce the manual drift that normally creeps in between API documentation and application code.

사업적 근거를 만들기

Strict typing does ask for some upfront investment, especially when older JavaScript code carries inconsistent data shapes. The return shows up over time: smaller refactors, clearer ownership, and far fewer integration surprises.

Start with the boundaries that carry the most risk:

위험성이 가장 높은 경계부터 시작하세요:
TypeScript 옵션 객체와 이벤트 페이로드를 입력하세요.
strict 컴파일러 체크를 점진적으로 활성화하세요.
업데이트 전 타입 체크를 요구하세요.

기업 모바일 팀에게는 이 기초가 플랫폼, 릴리즈, 기여자에 걸쳐 유지 관리를 예측할 수 있게 해줍니다.

Capacitor의 ScreenOrientationPlugin은 tuyệt vời한 TypeScript API 예제 이것은 단순한 웹 메소드를 플랫폼별 장치 동작에 매핑하는 몇 가지 간단한 웹 메소드입니다. 공공 계약은 플랫폼 간에 동일한데, iOS와 Android는 각각 자신의 네이티브 세부 사항을 처리합니다.

import { registerPlugin } from ‘@capacitor/core’;

export type OrientationType = | ‘portrait-primary’ | ‘portrait-secondary’ | ‘landscape-primary’ | ‘landscape-secondary’;

export interface OrientationData { type: OrientationType; angle: number; }

export interface LockOptions { 방향: OrientationType; }

export interface ScreenOrientationPlugin { orientation(): Promise };\nlock(options: LockOptions): Promise;\nunlock(): Promise; addListener( eventName: ‘screenOrientationChange’, listenerFunc: (data: OrientationData) => void, ): Promise<{ remove: () => Promise} } ;

export const ScreenOrientation =\nregisterPlugin(‘ScreenOrientation’);

각 메서드의 서명에 대한 빠른 참조입니다.

orientation() — 현재 방향을 비동기적으로 읽습니다.
lock() — 알려진 방향 값만 허용합니다.
unlock() — 일반 장치 동작으로 제어를 되돌려줍니다.
addListener() — 방향이 변경될 때마다 타입화된 데이터를 전달합니다.

각 메서드는 Promise를 반환하므로, native bridge와 브라우저 구현 모두에 대해 동일한 호출 패턴을 사용할 수 있습니다. Branching이나 special case가 필요하지 않습니다.

const current = await ScreenOrientation.orientation();

if (current.type.startsWith('landscape')) { console.logAngle: ${current.angle}); }

await ScreenOrientation.lock({orientation: 'landscape-primary',});

잘못된 값을 입력하면 즉시 빌드가 실패합니다. 그건 몇 초 만에 고칠 수 있는 컴파일 오류 — 플랫폼에 종속된 런타임 버그를 디바이스 로그를 통해 추적하는 것이 아닙니다. landscape-main 정확한 OrientationData를 전달하십시오

리스너는 일반 메소드와 마찬가지로 엄격한 rigor를 기대합니다.

리스너의 콜백 함수에서 return 값을 반환하는 것과 이벤트의 데이터를 전달하는 것을 구분하는 것이 중요합니다. any const handleChange = (data: OrientationData) => { document.body.dataset.orientation = data.type; }; orientation() returns.

await subscription.remove();

ScreenOrientation.orientation();

ScreenOrientation.lock({ orientation: ‘landscape-primary’, });

단일 타입만 공유하세요. OrientationData native 구현이 동일한 field를 보장할 때만. angle, 옵션으로 처리하고 호출자에게 처리하도록 강제하세요. undefined.

설계 선택	안전한 패턴
입력	명명된 옵션 인터페이스
결과	Explicit Promise 타입
이벤트	Literal 이벤트 이름
정리	취소할 수 있는 구독을 반환하십시오.

인터페이스는 브리지 계약이 아닌 원시 구현체입니다. 작고 예측 가능한 테스트 가능한 것을 유지하십시오.

플랫폼 동작, 권한, 설치 단계에 대한 정보는 Capacitor 화면 방향 플러그인 가이드를 참조하십시오. 마지막으로, 잘못된 메서드 이름, 누락된 필드, 불일치한 리스너 데이터를 잡아내기 위해 strict TypeScript 설정에서 유효한 호출과 거부된 호출을 모두 테스트하는 습관을 들으십시오. 이 combination은 앱을 패키징하기 전에 오류를 잡아내는 데 도움이 됩니다.

Capgo gives Capacitor teams a way to push JavaScript, CSS, configuration, and asset fixes without sitting through app store review. The trick is treating its update pipeline like any other typed API boundary, so channels, rollout rules, compatibility checks, and rollback decisions stay explicit before a bundle ever reaches a user’s device.

A person holding a smartphone showing the difference between portrait and landscape screen orientation modes.

스마트폰을 들고 있는 사람의 사진.

업데이트 계약을 정의하십시오.

type Channel = ‘beta’ | ‘staging’ | ‘production’;

interface UpdateResult { accepted: boolean; appliedOnNextLaunch: boolean; rollbackEnabled: boolean; }

간단한 TypeScript API 예시 validates the request before handing it off to the Capgo 클라이언트:

async function publishUpdate( request: UpdateRequest, ): Promise { if (!request.signed || request.rolloutPercent < 0 || request.rolloutPercent > 100) { throw new Error(‘unsafe update request’); }

capgo.publish(request);

The exact client method name shifts between Capgo SDK versions, so wrap it behind your own interface. That isolation pays off every time you upgrade and keeps vendor-specific details from leaking across your codebase.

채널 보호 및 호환성

채널을 선택하는 건 간단히 할 수는 없습니다. 프로덕션 릴리즈는 베타 실험보다 엄격한 검사를 요구하며, 웹 번들을 통해 native 기능을 호출할 때 특히 이전 앱 버전에서 존재하지 않았던 기능을 호출할 때 더욱 그렇습니다.

function canDeploy( request: UpdateRequest, installedNativeVersion: string, ): boolean { return request.signed && installedNativeVersion >= request.minNativeVersion; }

버전 비교는 단순 문자열 비교로 하지 말고, 적절한 의미 버전 라이브러리를 불러와서 사용하십시오. 1.10.0 정렬 후 1.9.0. 배포 전 채널에 도달하기 전에 체크리스트를 실행하십시오:

배포가 서명되었는지 확인하십시오.
목적에 맞는 채널이 맞는지 확인하십시오.
자연어와 배포 호환성 범위 비교하십시오.
제한된 사용자에게 먼저 배포하십시오.
실패 신호를 감시하고 롤백 준비하십시오.

타입스크립트 API 예제 Note: I shortened the wording while keeping the same meaning, and preserved the placeholder code.

Capgo의 차이 배포 및 채널 제어는 패턴에 잘 맞고, 장치 수준의 관찰성은 팀이 추적하거나 실패 신호를 추적할 수 있도록 해줍니다. 이 가이드는 사용자 지정 이벤트 추적에 대한 Capgo.

__CAPGO_KEEP_0__의 사용자 정의 이벤트 추적 가이드를 참조하십시오.

Typed listeners are what make asynchronous APIs easy to trust. Whether a callback tracks screen orientation or a Capgo update event, it should receive the same payload shape on every platform — and the compiler should be the one enforcing that.

interface UpdateEvent { version: string; channel: ‘beta’ | ‘production’; available: boolean; }

Listener (payload: T) => void;

interface UpdateService { addListener( event: 'updateAvailable', callback: Listener )Promise<{ remove: () => Promise}> }>;\nremoveAllListeners(): Promise; }

This TypeScript API 예제 이벤트 이름을 Literal로 고정하고 callback을 타입화된 데이터로 연결합니다. 편집기에서는 자동완성 기능을 지원합니다. version for free, and the compiler rejects any callback that expects unrelated data. It’s a small amount of setup, and it pays off every time the API changes.

안전하게 리스너 등록하기

__CAPGO_KEEP_0__

Inside a component, keep the subscription handle around so cleanup stays explicit. The same pattern drops into Angular lifecycle hooks, React effects, and Vue mount hooks without changes.

let orientationHandle: { remove: () => Promise} } | undefined;

async function stop() { await orientationHandle?.remove(); orientationHandle = undefined; }

Each framework gives you a hook for this:

Angular

Angular React ngOnDestroy
React Vue useEffect
Vue — 구독을 취소하세요. onBeforeUnmount

모든 addListener 콜은 일치하는 제거 경로가 있어야 합니다.

정확한 청소 방법을 선택하세요.

한 구성 요소가 한 구독을 소유할 때 반환된 핸들은 올바른 호출입니다. removeAllListeners() 서비스가 여러 리스너를 보유하고 완전히 초기화될 때 빛을 내립니다.

async function resetUpdates(service: 업데이트 서비스) { await service.removeAllListeners(); }

공유 구성 요소에서 다른 화면이 서비스에依存하고 있는 동안 넓은 메서드를 호출하지 마십시오. 소유권이 지역적일 때, 개별 remove() 핸들을 사용하세요.

상황	권장 hành위
한 구성 요소 구독	호출 `handle.remove()`
서비스 종료	호출 `removeAllListeners()`
중복 등록	보호 초기화
알 수 없는 데이터	사용하기 전에 검증

Capgo 알림에 대해, 업데이트 데이터와 장치 이벤트를 분리하고, 각각의 테스트를 진행하세요. 그 후, 등록, 전달, 정리 과정을 테스트하세요. Capgo 커스텀 이벤트 추적 가이드는 통합에 대한 더 많은 정보를 제공합니다. Capgo 사용자 정의 이벤트 추적 가이드 통합 측면에서 더 많은 정보가 있습니다.

Capacitor

code

A 잘 구축된 A TypeScript API 예제 명확한 이름으로 시작합니다. 메서드에 동사, 인터페이스에 명사, 일관된 접미사(예: )를 사용하세요. Options, Result, Event명확한 이름은 개발자가 구현을 열지 않고도 계약을 이해할 수 있게 해서 온보딩 시간을 단축합니다.

공개 인터페이스를 작게 유지하세요. 관련이 없는 연산을 단일 객체에 던지지 않고 대신 특정한 메서드를 통해 기능을 노출하세요.

getStatus() 상태를 읽습니다.
updateConfig(options) 설정을 변경합니다.
addListener(event, callback) 변경을 구독합니다.

입출력을 명확하게 지정하세요.

명명된 옵션 인터페이스를 사용하여 매개변수가 증가할 수 있는 경우:

interface PublishOptions { channel: ‘beta’ | ‘production’; rolloutPercent: number; }

interface PublishResult { version: string; accepted: boolean; }

async function publish(__CAPGO_KEEP_0__) return client.publish(options);

유형이 다른 API가 감싸지만, 그들의 특정 타입을 보존해야 하는 경우, generics는 그 자리에서 빛을 발합니다:

응답 API 인터페이스 {\ndata: T;\nrequestId: string;\n}

async function request(path: string): Promise<ApiResponse>fetchJson<ApiResponse>>(경로);\n}

단순히 유연한 것처럼 보이기 위해 generics를 추가하지 마세요. generics는 입력과 출력 사이에 실제 관계를 표현해야 합니다. 그 외의 경우, 구체적인 인터페이스가 더 읽기 쉽고 유지 보수하기 쉬울 것입니다.

유효하지 않은 상태를 표현하기 어렵게 하세요특히 네이티브, 네트워크 및 업데이트 경계에서.

계약과 함께 동작을 문서화하십시오. 권한, 단위, 거부된 약속, 선택 필드 및 메서드가 즉시 적용되거나 다음 런칭 시 적용되는지에 대해 설명하십시오. 인라인 주석은 결정을 설명하는 것이며 메서드 이름을 재사용하지 않도록 하십시오.

변경 사항을 위한 Code 정렬

변경 사항을 위한 __CAPGO_KEEP_0__ 정렬

관심사	권장 위치
공개 인터페이스	`types.ts`
API 메서드	`client.ts`
네이티브 어댑터	`platform/`
호환성 테스트	`tests/`

플러그인 변경이 깨질 경우, 새로운 주요 인터페이스나 호환성层를 도입하고, 잠시 더 유지하고, 마이그레이션 단계를 기록하십시오. API 버전 관리 전략에 대해 더 알아보십시오. 변경 전 소비자.

CI에서 strict type 체크 및 계약 테스트를 실행하고 shipping하기 전에 Capgo 워크플로우에서 채널 값, 네이티브 호환성, 서명된 번들 및 롤백 동작을 유형화된 릴리스 규칙으로 확인하세요. 이렇게 하면 팀, 플랫폼 및 통합이 성장하는 동안 빠른 업데이트를 제어할 수 있습니다.

동적 네이티브 결과를 어떻게 타입화해야 하나요?

Don’t let any leak into your code when a native method hands back unpredictable data. Instead, spell out the fields you can count on, mark genuinely optional values with ?실제로 옵션인 값을 표시하고, 불확실한 입력을 경계에서 sanitize하세요.

interface NativeResult { 성공: boolean; 값?: string; }

async function readValue(): Promise const result = await NativePlugin.read(); return { success: Boolean(result.success), value: typeof result.value === ‘string’ ? result.value : undefined, };

이 접근 방식은 타입 자체에서 불확실성을 명시적으로 표시하면서도 호출자에게 안전성을 유지합니다. broader look을 원하시면 TypeScript로 API를 빌드하는 방법.

리스너는 어떻게 미처리된 거부를 피할 수 있나요?

Asynchronous callbacks need to be defensive by design. Failures inside the listener itself should be caught rather than trusting the event system to swallow rejected promises silently.

const handleUpdate = (event: UpdateEvent): void => { void applyUpdate(event).catch((error: unknown) => { console.error(‘Update failed’, error); }); }

Component unmounting should hold onto the subscription reference and remove it. This prevents duplicate callbacks and stale state updates.

모든 비동기 리스너는 오류 경로와 정리 경로가 모두 필요합니다.

Capgo 업데이트를 어떻게 보호하나요?

Signing keys and administrative credentials should be stored on the server or CI system. The client should only receive signed bundles and use typed results to display status.

게시 전에 별도의 채널 연합을 설정하고, 호환성 검사를 실행하고, 롤아웃 제한을 구성하고, 롤백 경로를 계획하세요. Capgo Capgo handles signed delivery, channel controls, next-launch application, and rollback protection for Capacitor and Electron apps.

TypeScript API 예시: Capacitor 및 Capgo

목차