@mornya/platform-libs/README.md

Parses UA (user-agent) information of the current platform.

# Platform Libs
![npm](https://img.shields.io/npm/v/@mornya/platform-libs)
![node](https://img.shields.io/node/v/@mornya/platform-libs)
![types](https://img.shields.io/npm/types/@mornya/platform-libs)
![downloads](https://img.shields.io/npm/dw/@mornya/platform-libs)
![license](https://img.shields.io/npm/l/@mornya/platform-libs)

Parses UA (user-agent) information of the current platform.

> This project has been created by [Vessel CLI](https://www.npmjs.com/package/@mornya/vessel).
  For a simple and quick reference about it, click [here](https://mornya.github.io/documents/guide/vessel.md).

## About
현재 웹 플랫폼에서 사용자 에이전트 정보를 추출하는 라이브러리.

## Installation
해당 라이브러리를 사용 할 프로젝트에서는 아래와 같이 의존성 모듈로 설치한다.
```bash
$ npm install --save @mornya/platform-libs
or
$ yarn add @mornya/platform-libs
```

## Usage
아래와 같이 모듈을 import하여 사용한다.
```typescript
import { Platform } from '@mornya/platform-libs';
```

## Modules in the package
본 패키지에는 아래와 같은 모듈들을 포함한다.<br>
제공되는 모듈과 메소드 사용법 등은 코드 스니핏을 참고한다.

### Platform module
샘플 모듈은 다음과 같은 메소드들을 제공한다.

#### `Platform.getInfo`
파라미터로 전달된 사용자 에이전트 문자열을 분석하여 추출된 내용을 오브젝트 형태로 반환한다.
```typescript
import { Platform } from '@mornya/platform-libs';

const platformInfo = Platform.getInfo(navigator.userAgent);

console.log(platformInfo);
```

반환되는 오브젝트는 아래 기본 인터페이스 구조를 참고.
```typescript
{
  // OS 벤더 구분
  OS: {
    vendor: string; // 'AOS' | 'IOS' | 'WOS' | 'WIN' | 'MAC' | 'LINUX';
    version: string; // OS 벤더 버전 (semver 형태)
  };
  // 브라우저(웹/앱) 구분 
  Browser: {
    type: string; // 'APP' | 'MWEB' | 'PC';
    vendor: string; // 'CHROME' | 'SAFARI' | 'FIREFOX' | 'OPERA' | 'IE';
    version: string; // 브라우저 벤더 버전 (semver 형태)
  };
  // UserAgent 문자열 추출 정보
  UA: {
    productName: string;
    productVersion: string;
    systemInfo: string;
    extras?: string;
  };
  isDesktop: boolean; // 데스크탑 PC에서의 브라우징 여부
  isMobile: boolean; // 모바일에서의 브라우징 여부 (네이티브 앱 일때에도 true)
  isAOS: boolean; // OS가 Android인지 여부
  isIOS: boolean; // OS가 iOS인지 여부
}
```

#### `Platform.checkVersion`
semver 형태의 버전을 서로 비교하여 대상 버전이 높은지(1) 같은지(0) 낮은지(-1)를 판별한다.
```typescript
import { Platform } from '@mornya/platform-libs';

const baseVersion = '1.0.0';
console.log(Platform.checkVersion(baseVersion, '1.1.0')); // 1
console.log(Platform.checkVersion(baseVersion, '1.0.0')); // 0
console.log(Platform.checkVersion(baseVersion, '0.9.0')); // -1
```

#### `Platform.resolveMatches`
정규식을 이용하여 매치되는 브라우저 정보를 커스터마이즈하여 추가하기 위해 사용한다.
```typescript
import { Platform } from '@mornya/platform-libs';

type ExtraBrowserType = 'APP'; // 추가 될 브라우저 타입
type ExtraBrowserVendor = 'APP1' | 'APP2'; // 추가 될 브라우저 벤더명

interface IPlatformExtendInfo extends Platform.Info<ExtraBrowserType, ExtraBrowserVendor> {
  isNative?: boolean;
  isAPP1?: boolean;
  isAPP2?: boolean;
}

const platformInfo = Platform.getInfo<IPlatformExtendInfo>(navigator.userAgent);

// 네이티브 앱 브라우저 정보 등록 샘플
// UA 문자열에 앱 관련 정보가 있어야 함
// ex) my-native-app1/1.2.3
const extras = {
  APP1: [/my-native-app1\/([0-9]+)\.([0-9]+)\.([0-9]+)/],
  APP2: [/my-native-app2\/([0-9]+)\.([0-9]+)\.([0-9]+)/],
};
const { name, matches } = Platform.resolveMatches(extras, platformInfo.UA.extras);

if (['APP1', 'APP2'].includes(name)) {
  platformInfo.Browser.type = 'APP';
  platformInfo.Browser.vendor = name; // 정규식으로 매칭된 키 (APP1 or APP2)
  platformInfo.Browser.version = [matches[1], matches[2], matches[3]].join('.'); // semver 형태
  platformInfo.isMobile = true;
  platformInfo.isNative = true;
  platformInfo.isAPP1 = name === 'APP1';
  platformInfo.isAPP2 = name === 'APP2';
} else {
  platformInfo.isNative = false;
  platformInfo.isAPP1 = false;
  platformInfo.isAPP2 = false;
}

console.info(platformInfo);
```

#### `Platform.isTouchDevice`
현재 디바이스가 터치 가능한 디바이스인지 여부를 리턴한다.
```typescript
import { Platform } from '@mornya/platform-libs';

console.log(Platform.isTouchDevice()); // true or false
```

## Change Log
프로젝트 변경사항은 [CHANGELOG.md](CHANGELOG.md) 파일 참조.

## License
프로젝트 라이센스는 [LICENSE](LICENSE) 파일 참조.