@devdzipup/partners

Zipup OpenAPI를 React Native(iOS/Android) 앱에서 사용할 수 있게 해주는 네이티브 SDK입니다.

설치

1. 패키지 설치

npm install @devdzipup/partners

또는

yarn add @devdzipup/partners

2. iOS 전용 (CocoaPods)

iOS 프로젝트에서 한 번 실행합니다.

cd ios && pod install && cd ..

iOS — onOpen에서 Linking.openURL로 https/http 열기

iOS 9 이상에서는 시스템이 canOpenURL로 https·http 스킴을 조회할 때, 앱의 Info.plist에 LSApplicationQueriesSchemes 로 선언되어 있어야 합니다. 없으면 Safari로 열어도 React Native Linking.openURL이 Unable to open URL: https://... 처럼 실패할 수 있습니다.

앱의 ios/YourApp/Info.plist (또는 Xcode Target → Info)에 추가하세요:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>https</string>
  <string>http</string>
</array>

(이미 LSApplicationQueriesSchemes 배열이 있다면 https·http 항목만 추가하면 됩니다.)

3. Android (Gradle)

이 패키지를 사용하는 앱의 Android 프로젝트에서, 저장소(repositories) 설정에 아래를 추가합니다.
mavenCentral()이 이미 있다면 중복으로 넣지 않고, 없는 항목만 추가하면 됩니다.

android/settings.gradle / settings.gradle.kts의 dependencyResolutionManagement { repositories { ... } } 또는, 프로젝트 구조에 따라 루트 build.gradle의 allprojects { repositories { ... } } 등 repositories { } 블록 안에 넣습니다.

Kotlin DSL (.gradle.kts)

mavenCentral()
maven { url = uri("https://jitpack.io") }

Groovy (build.gradle)

mavenCentral()
maven { url 'https://jitpack.io' }

4. 환경 요구 사항

• React Native 0.83.0 이상
• iOS 13.0+ / Android API 21+

빠른 시작

아래 순서만 지키면 바로 동작합니다.

1. 초기화
2. 이벤트 구독
3. 화면 열기
4. 정리

예시

import { useEffect, useState } from 'react';
import { Button, Text, Alert, Linking } from 'react-native';
import {
  init,
  open,
  close,
  addListener,
  removeListener,
} from '@devdzipup/partners';

// USER_KEY, USER_PHONE: Zipup-SDK에 사용할 사용자의 고유 식별 정보
const USER_KEY = 'your-user-key';
const USER_PHONE = '01012345678';
const PROXY_URL = 'https://your-proxy-url';

function ZipupScreen() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    const result = init(USER_KEY, USER_PHONE, PROXY_URL);
    if (result.startsWith('error:')) {
      console.error('Zipup init 실패:', result);
      return;
    }

    const sub = addListener((e) => {
      if (e.event === 'ready') setReady(true);
      if (e.event === 'onOpen' && e.data?.url) Linking.openURL(e.data.url);
      if (e.event === 'onClose') setReady(false);
    });

    return () => removeListener(sub);
  }, []);

  const handleOpen = () => {
    const result = open();
    if (result.startsWith('error:')) {
      Alert.alert('오류', 'Zipup을 열 수 없습니다.');
    }
  };

  return (
    <>
      <Button title="Zipup 열기" onPress={handleOpen} />
      {ready && <Text>연동 준비됨</Text>}
    </>
  );
}

위 코드를 복사한 뒤 USER_KEY, USER_PHONE, PROXY_URL만 실제 값으로 바꾸면 동작합니다.

API 사용법

import

import {
  init,
  open,
  close,
  addListener,
  removeListener,
} from '@devdzipup/partners';

init

SDK를 사용자 정보로 초기화합니다. Zipup 화면을 띄우기 전에 한 번만 호출하면 됩니다. (앱 기동 시 또는 로그인 직후 권장)

init(userKey: string, userPhone: string, proxyUrl: string): string;

반환값: 성공 시 "init success" 등 성공 메시지, 실패 시 "error: ..." 문자열.

예시

const result = init(USER_KEY, USER_PHONE, PROXY_URL);
if (result.startsWith('error:')) {
  console.error('Zipup init 실패:', result);
  return;
}
// 이후 open() 호출 가능

open

Zipup SDK 화면을 엽니다. "Zipup 열기" 버튼 클릭 등 사용자가 SDK 화면을 보려는 시점에 호출합니다.

open(): string;

주의

• open()을 호출하기 전에 반드시 init()이 성공한 상태여야 합니다.
• SDK 내부 웹뷰에 웹 페이지가 로드되면 ready 이벤트가 전달됩니다. 이 시점부터 Zipup 화면이 정상적으로 사용 가능한 상태입니다.
• open() 호출 후 10초 이내에 ready 이벤트를 받지 못하면 타임아웃으로 간주되어 SDK가 자동으로 close()를 호출합니다. 네트워크 지연이나 로드 실패 시 재시도하거나 사용자에게 안내하는 처리를 고려하세요.

예시

const result = open();
if (result.startsWith('error:')) {
  showToast('Zipup을 열 수 없습니다.');
}

close

Zipup SDK 화면을 닫습니다. 사용자가 "닫기"를 눌렀을 때나, onClose 이벤트 후 정리할 때 호출합니다.

close(): string;

예시 (이벤트 콜백 안에서 호출할 때)
콜백 안에서 바로 close()를 부르면 문제가 될 수 있으므로, 한 틱 미뤄서 호출하는 것을 권장합니다.

if (e.event === 'onClose') {
  setTimeout(() => close(), 0);
}

addListener / removeListener

이벤트를 구독·해제할 때 사용합니다. Zipup 화면을 열 계획이 있는 컴포넌트에서 마운트 시 addListener, 언마운트 시 removeListener를 호출하세요.

const sub = addListener((event) => {
  callback(event.event, event.data);
});

// 컴포넌트 언마운트 시
removeListener(sub);

이벤트 타입

type ZipupEventData = {
  event: 'onOpen' | 'onClose' | 'ready';
  data?: Record<string, any>;
};

예시 (React useEffect)

useEffect(() => {
  const sub = addListener((e) => {
    if (e.event === 'onOpen' && e.data?.url) {
      Linking.openURL(e.data.url);
    }
    if (e.event === 'onClose') {
      setTimeout(() => close(), 0);
    }
  });
  return () => removeListener(sub);
}, []);

이벤트 설명

이벤트는 SDK 내부에서 1차적으로 처리된 뒤, addListener로 등록한 콜백을 통해 앱에 전달됩니다. 따라서 SDK를 사용하는 쪽에서는 콜백에서 이벤트를 받아 로딩 UI, 브라우저 열기, 화면 닫힘 처리 등 부가적인 동작을 구현할 수 있습니다.

| 이벤트 | 설명 | 활용 | | --------- | ------------------------ | ---------------------------------------------------------------------------- | | onOpen | SDK 열림 (URL 포함 가능) | data.url이 있으면 Linking.openURL(data.url) 등으로 외부 브라우저 열기 | | ready | SDK 준비 완료 | 로딩 UI 숨기기, "준비됨" 상태 표시. 10초 타임아웃이 이 이벤트 수신 시 해제됨 | | onClose | SDK 종료 | 화면 닫힘 처리, 상태 초기화. 필요 시 setTimeout(() => close(), 0) 호출 |

권장 호출 순서

| 순서 | 작업 | 설명 | | ---- | ----------------------- | ------------------------------------------------------------------ | | 1 | init(...) | 앱/화면 진입 시 한 번. 실패 시 open 호출 금지 | | 2 | addListener(callback) | open 전에 구독. onOpen 시 URL 있으면 Linking.openURL 등 처리 | | 3 | open() | 사용자 액션(버튼 등)에서 호출 | | 4 | (선택) close() | 사용자가 닫기 시 등. 타임아웃 시 자동 호출됨 | | 5 | removeListener(sub) | 컴포넌트 언마운트 시 반드시 호출 |

주의사항

• 컴포넌트 언마운트 시: 반드시 removeListener(구독객체)를 호출하세요. useEffect cleanup에서 return () => removeListener(sub) 형태로 두면 됩니다.
• init 실패 시: open()을 호출하지 말고, 사용자에게 "잠시 후 다시 시도해 주세요" 등 안내를 하세요.
• open() 호출 전: init()이 성공한 뒤이고, addListener로 이벤트를 미리 등록해 두는 것이 안전합니다.

문의

• 홈페이지: https://www.zipup.co.kr/