API 가이드 – Developer guides

HerculesPlugin 클래스 및 API

기본 API 목록입니다.
모든 API들은 HiveSDK가 초기화 된 이후에 사용할 수 있습니다.

IsJailbrokenDevice (iOS)

- iOS 기기가 탈옥 상태인지 확인합니다.

uint IsJailbrokenDevice();         // C#
uint HerculesIsJailbrokenDevice(); // C, C++

1 2	uint IsJailbrokenDevice(); // C# uint HerculesIsJailbrokenDevice(); // C, C++

반환 값
- 순정 펌웨어 상태이면 0, 탈옥된 기기이면 0이 아닌 값이 반환됩니다.
매개변수
- 없음

IsRootedDevice (Android)

- 안드로이드 기기가 루팅된 상태인지 확인합니다.

uint IsRootedDevice();         // C#
uint HerculesIsRootedDevice(); // C, C++

1 2	uint IsRootedDevice(); // C# uint HerculesIsRootedDevice(); // C, C++

반환 값
- 루팅되지 않은 상태이면 0, 루팅된 기기이면 0이 아닌 값이 반환됩니다.
매개변수
- 없음

IsEmulator (Android)

- 안드로이드 기기가 에뮬레이터인지 확인합니다.

uint IsEmulator();         // C#
uint HerculesIsEmulator(); // C, C++

1 2	uint IsEmulator(); // C# uint HerculesIsEmulator(); // C, C++

반환 값
- 모바일 기기이면 0, 에뮬레이터이면 0이 아닌 값이 반환됩니다.
- 에뮬레이터들은 모바일 기기로 보이도록 둔갑하기 때문에 특정 에뮬레이터의 경우 0이 반환될 수 있습니다.
매개변수
- 없음

IsUnofficialBuild (iOS)

- iOS 빌드가 비공식 빌드(앱스토어에서 내려받지 않은 빌드)인지 확인합니다.
- Fairplay 암호화 및 서명된 빌드인지 체크하며, AppStore 및 TestFlight에서 내려받은 빌드를 공식 빌드로 가정합니다.

uint IsUnofficialBuild();         // C#
uint HerculesIsUnofficialBuild(); // C, C++

1 2	uint IsUnofficialBuild(); // C# uint HerculesIsUnofficialBuild(); // C, C++

반환 값
- 공식 빌드이면 0 이며, 외부에서 설치된 빌드는 1 입니다. 확인에 실패하면 2 이상의 값이 반환됩니다.
매개변수
- 없음

GetFunnels (Android)

- 앱이 설치된 유입 경로를 얻어옵니다.

string GetFunnels();               // C#
const char * HerculesGetFunnels(); // C, C++

1 2	string GetFunnels(); // C# const char * HerculesGetFunnels(); // C, C++

반환 값
- 앱이 설치된 경로로 ADB, Google Play Store, Amazon Appstore와 같은 값이 반환되거나, 기타 다른 마켓 또는 파일탐색기 앱으로 설치한 경우 설치한 앱의 패키지명이 반환됩니다.

GetCertDesc (Android, iOS)

- 서명된 앱의 인증서 정보를 얻어옵니다

string GetCertDesc();              // C#
const char* HerculesGetCertDesc(); // C, C++

1 2	string GetCertDesc(); // C# const char* HerculesGetCertDesc(); // C, C++

반환 값
- Android: APK 키스토어의 Common Name 을 반환합니다.
- iOS: 프로비저닝 프로파일에 연결된 인증서 정보를 반환합니다. 앱스토어에서 내려받은 빌드는 빈 값입니다. 앱이 크랙된 경우 설치 방법에 따라 크랙 개발자의 인증서 또는 유저 개인의 인증서 이름이 표시됩니다.
매개변수
- 없음

GetTeamId (iOS)

- 프로비저닝 프로파일 소유자 계정의 팀 ID 를 얻어옵니다.

string GetTeamId();              // C#
const char* HerculesGetTeamId(); // C, C++

1 2	string GetTeamId(); // C# const char* HerculesGetTeamId(); // C, C++

반환 값
- 앱을 서명한 애플 개발자 계정의 팀 ID 이며, 영문과 숫자의 조합입니다.
- 앱이 크랙되는 경우 다른 계정으로 재 서명되어 아래 굵게 표시한 값들과 달라질 수 있습니다.

GetCertHash (Android)

- APK에 적용된 서명 해시를 얻어옵니다.

string GetCertHash();              // C#
const char* HerculesGetCertHash(); // C, C++

1 2	string GetCertHash(); // C# const char* HerculesGetCertHash(); // C, C++

반환 값
- APK 서명해시 값 입니다. SHA1 해시이며 16진수 형태의 40자리 문자열입니다.
- 구글플레이스토어 또는 아마존 등 업로드 후 서명키가 달라질 수 있습니다. 사용하는 서명키들의 해시값을 확인한 후 비교할 수 있습니다. 기존에 확인한 해시와 달라지는 경우 리패키징으로 볼 수 있습니다.

HerculesPrefs 클래스 및 API

유니티 엔진의 PlayerPrefs 클래스 형태의 암호화 버전입니다.
유니티와 달리 게임을 종료할 때 자동으로 저장이 되지 않으니, Save함수를 호출해야 합니다.
기기 백업 후 게임 데이터를 다른 기기로 옮기면, 암호화된 데이터도 같이 복사될 수 있습니다.

참고 URL: https://docs.unity3d.com/kr/530/ScriptReference/PlayerPrefs.html

GetInt, GetFloat, GetString

- 암호화 된 설정파일에 저장된 값을 얻어옵니다.

int GetInt(string key, int defaultValue = 0);
float GetFloat(string key, float defaultValue = 0.0f);
string GetString(string key, string defaultValue = "");

// C#
int HerculesPrefsGetInt(const char *key, int defaultValue = 0);
float HerculesPrefsGetFloat(const char *key, float defaultValue = 0);
char* HerculesPrefsGetString(const char *key, const char *defaultValue = "");

// C++

int GetInt(string key, int defaultValue = 0);

float GetFloat(string key, float defaultValue = 0.0f);

string GetString(string key, string defaultValue = "");

// C#

int HerculesPrefsGetInt(const char *key, int defaultValue = 0);

float HerculesPrefsGetFloat(const char *key, float defaultValue = 0);

char* HerculesPrefsGetString(const char *key, const char *defaultValue = "");

// C++

반환 값
- 저장되어 있던 값 입니다. 저장된 값이 없거나 변조된 것으로 판단되는 경우 defaultValue가 반환됩니다.
- C/C++의 HerculesPrefsGetString API에서 반환된 버퍼는 HerculesFreeMem API로 해제해야 합니다.
매개변수
- key : 얻어올 값의 키 입니다.
- defaultValue : 값이 없을 경우 반환될 기본 값 입니다.

SetInt, SetFloat, SetString

- key와 value을 암호화하여 보관합니다.
- Save API를 호출하지 않고 앱을 종료하면 설정된 내용이 손실됩니다.

void SetInt(string key, int value);
void SetFloat(string key, float value);
void SetString(string key, string value);

// C#
void HerculesPrefsSetInt(const char *key, int value);
void HerculesPrefsSetFloat(const char *key, float value);
void HerculesPrefsSetString(const char *key, const char *value);

// C++

void SetInt(string key, int value);

void SetFloat(string key, float value);

void SetString(string key, string value);

// C#

void HerculesPrefsSetInt(const char *key, int value);

void HerculesPrefsSetFloat(const char *key, float value);

void HerculesPrefsSetString(const char *key, const char *value);

// C++

반환 값
- 없음
매개변수
- key : 저장할 값의 키입니다.
- value : 저장할 값 입니다.

HasKey

- 키가 존재하는지 확인합니다.

bool HasKey(string key);                   // C#
uint HerculesPrefsHasKey(const char *key); // C, C++

1 2	bool HasKey(string key); // C# uint HerculesPrefsHasKey(const char *key); // C, C++

반환 값
- 키가 있으면 true(C#) 또는 1(C/C++)이 반환됩니다.
매개변수
- key : 테스트할 키 입니다.

DeleteKey

- 지정된 키를 삭제합니다.

void DeleteKey(string key);                   // C#
void HerculesPrefsDeleteKey(const char *key); // C, C++

1 2	void DeleteKey(string key); // C# void HerculesPrefsDeleteKey(const char *key); // C, C++

반환 값
- 없음
매개변수
- key : 삭제할 키 입니다.

DeleteAll

- 모든 키를 삭제합니다.

void DeleteAll();              // C#
void HerculesPrefsDeleteAll(); // C, C++

1 2	void DeleteAll(); // C# void HerculesPrefsDeleteAll(); // C, C++

반환 값
- 없음
매개변수
- 없음

Save

- 변경된 내용을 다시 한번 암호화하여 파일로 저장합니다. 저장된 내용은 모듈 초기화 시 불러옵니다.(Load)

void Save();         // C#
void HerculesSave(); // C, C++

1 2	void Save(); // C# void HerculesSave(); // C, C++

반환 값
- 없음
매개변수
- 없음

보안 변수 API (C/C++ 전용)

C/C++에서만 사용할 수 있는 보안변수 API 입니다.
C#에서는 보안변수 클래스 사용시 내부에서 호출됩니다.
사용방법은 별도 준비된 보안변수 사용가이드를 참고하는 것이 좋습니다.

AddString (C/C++ 전용)

- 문자열 형태의 Hercules 보안 변수를 추가합니다. (할당)

HERCULES HerculesAddString(const char *str);

1	HERCULES HerculesAddString(const char *str);

반환 값
- 생성한 보안 변수의 ID 입니다. 변수 생성에 실패하는 경우 0이 반환됩니다.
매개변수
- str : 원본 문자열의 포인터입니다.

AddVar (C/C++ 전용)

- Hercules 보안 변수를 추가합니다. (할당)

HERCULES HerculesAddVar(const void *data, uint length);

1	HERCULES HerculesAddVar(const void *data, uint length);

반환 값
- 생성한 보안 변수의 ID 입니다. 변수 생성에 실패하는 경우 0이 반환됩니다.
매개변수
- data : 변수 생성 시 참조할 초기값의 주소입니다.
- length : 생성할 변수의 크기입니다. data 매개변수의 크기를 설정합니다.

FreeMem (C/C++ 전용)

- HerculesGetString API 에서 할당된 버퍼를 해제합니다.

void HerculesFreeMem(void *ptr);

1	void HerculesFreeMem(void *ptr);

반환 값
- 없음
매개변수
- ptr : 일부 API 에서 할당된 버퍼의 주소입니다.

GetString (C/C++ 전용)

- Hercules 보안 문자열의 값을 읽어옵니다. (읽기)
- C++ 템플릿 클래스에서는 변수의 값 참조 시 자동으로 호출됩니다.
- 문자열을 읽어오는 시점에 값이 변조된 것을 감지하면 초기화 시 설정했던 콜백 함수가 호출됩니다. (정책에 따라 다릅니다.)

char* HerculesGetString(HERCULES seq);

1	char* HerculesGetString(HERCULES seq);

반환 값
- 값을 성공적으로 읽어 오면 문자열 버퍼를 반환하고 실패하면 nullptr을 반환합니다.
- 반환된 버퍼는 HerculesFreeMem 함수를 통해 해제해야 합니다
매개변수
- seq : 보안 변수의 ID 입니다.

GetVar (C/C++ 전용)

- Hercules 보안 변수의 값을 읽어옵니다. (읽기)
- C++ 템플릿 클래스에서는 변수의 값 참조 시 자동으로 호출됩니다.
- 변수를 읽어오는 시점에 값이 변조된 것을 감지하면 초기화 시 설정했던 콜백 함수가 호출됩니다. (정책에 따라 다릅니다.)

int HerculesGetVar(HERCULES seq, void *data);

1	int HerculesGetVar(HERCULES seq, void *data);

반환 값
- 값을 성공적으로 읽어 오면 0, 잘못된 파라미터는 양수, 변조가 감지되면 음수가 반환됩니다.
- 초기화 시 콜백 함수를 설정하지 않았다면 이 반환 값을 참조할 수 있습니다.
매개변수
- seq : 보안 변수의 ID 입니다.
- data : 읽어올 데이터 버퍼의 주소입니다. 변수 생성시 설정했던 크기와 동일한 크기의 버퍼를 설정해야 합니다.

RemoveVar (C/C++ 전용)

- Hercules 보안 변수를 제거합니다. (해제)
- C++ 템플릿 클래스에서는 변수 해제 시 자동으로 호출됩니다.

void HerculesRemoveVar(HERCULES seq);

1	void HerculesRemoveVar(HERCULES seq);

반환 값
- 없음
매개변수
- seq : 해제할 변수의 ID 입니다.

SetVar (C/C++ 전용)

- Hercules 보안 변수의 값을 설정합니다. (쓰기)
- C++ 템플릿 클래스에서는 변수에 값 대입 시 자동으로 호출됩니다.

void HerculesSetVar(HERCULES seq, const void *data);

1	void HerculesSetVar(HERCULES seq, const void *data);

반환 값
- 없음
매개변수
- seq : 보안 변수의 ID 입니다.
- data : 설정할 데이터 버퍼의 주소입니다. 변수 생성 시 설정했던 크기와 동일한 크기의 버퍼를 설정해야 합니다.