-1015, -21XX (SDK 인증 에러)

플랫폼별 초기화 방법

Android와 iOS는 SDK 초기화 API와 에러 확인 방식이 서로 다릅니다. 에러 발생 원인과 해결 방법에도 플랫폼별 차이가 있으므로, 검증을 시작하기 전에 대상 플랫폼을 먼저 확인하세요.

항목	Android	iOS
초기화 메서드	setCertification(key, expireDate, isTablet)	storage.applicationKey / applicationBundleID / applicationExpireDate 설정 후 start()
에러 확인 방법	getErrorCode() 반환값 확인 (동기 방식)	start() 실행 시 예외 처리 발생 (try/catch 방식)
인증 식별자	앱 패키지명(applicationId) 자동 추출	Bundle ID(CFBundleIdentifier) 명시적 입력
추가 파라미터	isTablet(모바일 및 태블릿 구분 값)	없음
디바이스 바인딩	setDevice(path, isTablet) 별도 호출 필요	start() 메서드 실행 시 내부적으로 자동 처리

---

-2103

• 에러 코드: -2103
• 타입: 플랫폼별로 상수명 상이
  • iOS: ERROR_INCORRECT_BUNDLE_ID
  • Android: ERROR_INCORRECT_PACKAGE_NAME
• 요약: SDK 초기화 시 전달한 인증 정보(키, 만료일, Bundle ID 또는 패키지명)가 발급 기록과 일치하지 않음

원인

원인	플랫폼	설명
Bundle ID 불일치	iOS	소스 코드의 storage.applicationBundleID 설정값이 프로젝트 Info.plist에 정의된 실제 CFBundleIdentifier 값과 다른 경우입니다.
패키지명 불일치	Android	SDK가 자동으로 추출한 앱의 패키지명과 라이선스 발급 시 등록한 패키지명(applicationId)이 다른 경우입니다.
Debug/Release 빌드 혼용	Android, iOS	빌드 구성(Variant/Target)별로 식별자를 다르게 설정해 둔 상태에서, 라이선스 키를 교차 복사하여 혼용한 경우입니다.
개발/운영 앱 혼용	Android, iOS	개발용(Debug) 키로 빌드한 앱을 운영 환경에서 실행하거나, 반대로 운영용(Release) 키를 개발 환경에서 테스트한 경우입니다.

주의

SDK 키 문자열과 만료일 날짜가 정확하더라도, Android의 패키지명이나 iOS의 Bundle ID가 등록된 정보와 다르면 -2103 에러가 발생하므로 주의하세요.

진단 (Android)

1. 초기화 코드가 호출되는 모듈의 build.gradle 파일을 열고 applicationId 값을 확인하세요.
2. 멀티 모듈 구조이거나 빌드 변형(Build Flavors/Product Flavors)을 사용하는 경우, 현재 빌드된 Variant의 최종 applicationId 문자열을 확인하세요.
3. SDK가 내부적으로 자동 추출한 패키지명과 라이선스 발급 시 등록한 패키지명이 정확히 일치하는지 비교하세요.

진단 (iOS)

1. Xcode 프로젝트 설정의 [Target] > [General] > [Identity] > [Bundle Identifier] 경로에 정의된 값을 확인하세요.
2. 소스 코드에서 storage.applicationBundleID에 대입한 문자열과 Xcode의 CFBundleIdentifier 값이 대소문자까지 완벽히 일치하는지 확인하세요.

storage.applicationBundleID = "com.example.myapp"  // Info.plist의 CFBundleIdentifier와 정확히 일치해야 합니다.

3. 빌드 구성(Debug/Release)에 따라 Bundle ID가 다르다면 빌드 환경별로 알맞은 applicationBundleID와 SDK 키가 매치되도록 분기 처리가 되어 있는지 확인하세요.

해결 방법

진단을 통해 발견된 불일치 식별자 항목을 수정한 후 다시 빌드하세요.

• 식별자(Bundle ID/패키지명) 자체를 완전히 변경해야 하는 경우, 기존 키는 사용할 수 없습니다. 기술 지원팀(PE, tech_support@catenoid.net)으로 키 재발급을 요청하세요.

---

-2104

• 에러 코드: -2104
• 타입: ERROR_EXPIRED_AUTH_DATE
• 요약: SDK 라이선스 유효 기간 만료

원인

원인	설명
라이선스 만료일 경과	SDK 발급 당시 등록한 라이선스 만료 날짜가 현재 시각 기준으로 이미 지났을 경우 발생합니다.
디바이스 시각 오설정	사용자의 디바이스 시스템 시간이 미래의 시간으로 설정되어 있어, 라이선스 유효성 검증을 통과하지 못하는 경우입니다.
일본력(和暦) 사용	일본 지역 디바이스의 운영체제 달력 설정이 일본력(레이와·헤이세이 등)으로 설정된 경우, 날짜 계산 오류로 인해 만료된 것으로 오탐지할 수 있습니다.

진단

1. 발급된 라이선스의 정확한 만료일을 확인하세요. (영업 담당자 또는 기술 지원팀의 발급 기록을 통해 확인할 수 있습니다.)
2. 디바이스의 날짜 및 시간 설정 메뉴에서 네트워크 동기화 시간(자동 설정)이 활성화되어 있는지 확인하세요.
   • Android: [설정] > [시스템] > [날짜 및 시간] > [자동으로 날짜 및 시간 설정]
   • iOS: [설정] > [일반] > [날짜 및 시간] > [자동으로 설정]
3. 일본 사용자의 디바이스인 경우, 운영체제의 달력 설정이 서력(西暦)으로 지정되어 있는지 확인하세요.

해결 방법

만료된 라이선스는 재발급을 받아 앱에 반영하기 전까지 SDK가 작동하지 않습니다.

• 라이선스 재발급: 기술 지원팀(PE, tech_support@catenoid.net)으로 문의하여 갱신된 키를 발급받으세요.
• 만료 임박 알림 조치: 라이선스 만료 전에 안내 메일이 발송되지만, 서비스의 안정성을 위해 고객사에서 자체적으로 만료일을 관리하는 것이 가장 안전합니다. 앱의 배포 주기와 SDK 만료일을 함께 기록하고 관리하세요.

---

-2106

• 에러 코드: -2106
• 타입: ERROR_INCORRECT_AUTH_KEY
• 요약: SDK 인증 키 불일치

원인

원인	플랫폼	설명
SDK 키 불일치	Android, iOS	소스 코드에 입력한 키 문자열이 발급받은 원본 키와 다릅니다.
만료일 형식 오류	Android, iOS	날짜 구분자 형식을 "YYYY/MM/DD" 규격이 아닌 다른 형식(YYYY-MM-DD, YYYYMMDD 등)으로 잘못 입력한 경우입니다.
개발/운영 앱 혼용	Android, iOS	개발용(Debug) 키로 빌드한 앱을 운영 환경에서 실행하거나, 반대로 운영용(Release) 키를 개발 환경에서 테스트한 경우입니다.
isTablet 불일치	Android	라이선스 발급 시 지정한 디바이스 타입(모바일/태블릿) 환경과 초기화 메서드의 setCertification(..., isTablet) 인자 값이 다르게 설정된 경우입니다.

진단 (Android)

1. 초기화 코드를 검증하세요.

// `getInstance` 호출 시 메모리 누수를 방지하기 위해 반드시 `Activity context` 대신 `ApplicationContext`를 사용하고 있는지 확인하세요.
mMultiStorage = MultiKollusStorage.getInstance(getApplicationContext());
boolean isTablet = Utils.getDeviceType(this) == Utils.DEVICE_TYPE.DEVICE_TABLET;
mMultiStorage.setCertification(
    "SDK_Key",       // 카테노이드에서 발급한 원본 키와 정확히 일치하는지 확인하세요.
    "YYYY/MM/DD",    // 반드시 슬래시(/) 구분자를 사용해야 하며 하이픈(-), 점(.)은 사용할 수 없습니다.
    isTablet         // 라이선스 발급 시 등록한 디바이스 타입과 일치해야 합니다.
);

2. 에러 코드 반환 방식을 확인하세요. iOS와 달리 Android 환경은 예외 처리(try/catch) 방식이 아니라 getErrorCode() 메서드의 반환값을 동기식으로 확인해야 합니다.

int nRet = mMultiStorage.getErrorCode();
if (nRet != ErrorCodes.ERROR_OK) {
    if (nRet == ErrorCodes.ERROR_INCORRECT_AUTH_KEY) {
        // 앱 키 만료 또는 인증 정보가 불일치하는 경우입니다. 
        // 앱을 최신 버전으로 업데이트하거나 tech_support@catenoid.net으로 문의하세요.
    }
    // 에러가 발생한 상태에서 재생 및 다운로드 시도를 진행하지 마세요.
    return;
}

3. 다음 순서대로 자가 진단을 진행하세요.
   1. 입력한 앱 키 문자열의 좌측과 우측에 불필요한 공백이나 줄바꿈(개행) 문자가 들어있는지 확인하세요.
   2. build.gradle 파일에 설정된 applicationId 값이 SDK 키 발급 신청 시 등록한 패키지명과 완벽히 일치하는지 확인하세요.
   3. 코드에 입력된 만료일 형식이 "YYYY/MM/DD" 형식인지 확인하세요.
   4. isTablet 값이 라이선스 발급 시 지정한 디바이스 타입과 일치하는지 확인하세요.

진단 (iOS)

1. 초기화 코드를 검증하세요.
   • 일본력 설정을 사용하는 디바이스의 날짜 오탐지를 방지하기 위해 반드시 캘린더 식별자를 gregorian으로 명시해야 합니다.

storage.applicationKey      = "SDK_Key"
storage.applicationBundleID = "com.example.myapp"  // Info.plist의 CFBundleIdentifier와 완벽히 일치해야 합니다.
let formatter = DateFormatter()
formatter.dateFormat = "YYYY/MM/DD"
formatter.calendar   = Calendar(identifier: .gregorian)  // 일본력 설정으로 인한 인식 오류 방지를 위해 필수적으로 추가하세요.
storage.applicationExpireDate = formatter.date(from: "2030/12/31")

2. 예외 처리 구조를 확인하세요. Android와 달리 iOS 환경은 storage.start() 또는 startWithCheck() 메서드가 에러를 throw하므로 try/catch 구문으로 감싸서 구현해야 합니다.

do {
    try storage.start()   // 또는 startWithCheck()
} catch {
    // (error as NSError).code 구문으로 에러 코드를 추출하여 확인하세요.
    // 반환된 에러 코드가 -2106인 경우 applicationKey, applicationBundleID, applicationExpireDate 설정을 다시 점검해야 합니다.
}

3. 다음 순서대로 자가 진단을 진행하세요.
   1. Xcode 프로젝트 타깃 설정의 [General] > [Identity] > [Bundle Identifier] 경로에 등록된 값이 소스 코드의 applicationBundleID와 대소문자까지 정확히 일치하는지 확인하세요.
   2. 빌드 구성(Debug/Release)에 따라 Bundle ID가 다르다면, 각 빌드 환경별로 알맞은 SDK 키가 매핑되어 있는지 확인하세요.
   3. formatter.calendar = Calendar(identifier: .gregorian) 구문이 누락되어 일본 디바이스 환경에서 만료일이 잘못 탐지된 것은 아닌지 확인하세요.

해결 방법

• 자가 진단을 통해 발견된 불일치 파라미터 항목을 올바르게 수정한 후 앱을 다시 빌드하세요.
• 패키지명(Android) 또는 Bundle ID(iOS)가 변경되어 신규 라이선스 키 재발급이 필요한 경우, 기술 지원팀(PE, tech_support@catenoid.net)으로 문의하세요.

---

-1015 (Android SDK)

• 에러 코드: -1015
• 타입: ERROR_UNSUPPORTED_DEVICE
• 요약: setDevice() 메서드 호출 시점 또는 DRM 호환성 검증 시 발생하는 에러 (Android 운영체제에서만 발생)

원인

원인	설명
인자 값에 null 전달	setDevice(path, isTablet) 메서드를 호출할 때 디바이스 경로 파라미터에 null이 전달되는 경우입니다.
DRM 미지원 디바이스	하드웨어가 Widevine를 지원하지 않거나, 루팅(Rooting)이 감지된 디바이스에서 DRM 콘텐츠를 재생하려고 하는 경우입니다.
에뮬레이터	AVD(Android Virtual Device) 환경에서 DRM 콘텐츠를 재생하려고 하는 경우입니다.

진단

소스 코드 내에서 setDevice()를 호출하는 시점에 파라미터 값으로 null이 전달되고 있지 않은지 아래 구현 코드를 바탕으로 검증하세요.

// 올바른 setDevice 구현 방법
storage.setDevice(
    Build.MANUFACTURER + "/" + Build.MODEL,  // 실제 디바이스 모델명을 식별자로 활용하세요. (null 입력 금지)
    isTablet
);

해결 방법

setDevice() 파라미터에 null 대신 실제 디바이스 식별 문자열이 전달되도록 코드를 정정하세요.