GameShield sdk 통합 가이드(네이티브 라이브러리 버전 2025)

통합 전 준비

연동을 시작하기 전에 자신의 비즈니스를 분류하고 SDK에 액세스해야 하는 비즈니스를 확인한 후 해당 비즈니스 포트, 도메인 이름 및 비즈니스 서버 IP를 지정하는 것이 좋습니다(참고: 비즈니스 서버 IP는 공용 네트워크에 노출되지 않아야 하며, 확인을 통해 얻을 수 없으므로 나머지 비즈니스와 분리하는 것이 바람직합니다).

다음과 같은 SDK 액세스 인스턴스를 만듭니다.생성에 성공하면 AppID와 AppKey를 얻게 됩니다.

포워딩 규칙 구성

각 전달 규칙은 전달 키(전달 규칙을 고유하게 나타내는), 소스 서버의 IP/도메인 이름, 포트 및 통신 프로토콜(tcp/udp)을 식별해야 합니다.

액세스 프로세스

다음 필수 인터페이스를 호출하기만 하면 됩니다.

• Init 인터페이스 초기화를 호출하고 매개변수 AppID, AppKey를 전달합니다(두 매개변수는 필수이며 반드시 호출해야 함). 초기화 후 가능한 한 빨리 클라이언트를 시작하고 굿(앱이 배경을 잘라낸 다음 다시 호출해야 함)을 초기화합니다.
• GetTCPServerAddr 인터페이스를 호출하여 로컬 TCP 프록시 IP와 포트(TCP 포워딩에 필요)를 가져옵니다.
• GetClientIP 인터페이스를 호출하여 클라이언트의 실제 IP를 가져옵니다(비즈니스에 따라 호출 여부 선택, 필수는 아님).
• 비즈니스 데이터는 HTTP 프로토콜 또는 TCP의 요청 헤더 X-Forward-For를 통해 소스로 다시 캡슐화됩니다.
• 현지 상담원과 링크를 설정하고 요청을 보냅니다.

통합 고려 사항

• Android, IOS, PC, http, tcp, 웹소켓에 관계없이 요청을 시작하고 연결을 끊었다가 다시 연결할 때마다, 그리고 화면 잠금 후 프로그램을 다시 시작할 때마다 GetTCPServerAddr을 다시 호출해야 하며 이전 반환 결과를 캐시에 저장할 수 없습니다. 시스템이 로컬 프록시 포트를 닫을 수 있으므로 인터페이스를 직접 다시 호출하여 연결을 구축하지 않으면 연결 실패가 발생하여 비즈니스 예외가 발생합니다.
• 안드로이드는 동적 라이브러리의 armeabi-v7a, x86, x86_64, arm64-v8 버전을 제공하며, 모든 안드로이드 디바이스와 호환될 수 있으며, 다른 타사 SDK는 라이브러리 파일을 일관되게 유지해야 하며, 그렇지 않으면 프로그램 충돌이 발생할 수 있습니다.
• 시뮬레이터를 차단해야 하는 경우.기술팀에 문의하세요..
• ios 잘 통합되는 .a 파일을 제공합니다(아이폰5 이전 기기는 더 이상 지원되지 않음).
• 클라이언트 측 네트워크 처리(예: 시간 초과 처리, 연결 끊김 후 재연결)는 더욱 강력해야 합니다.
• SDK 노드가 크고 불규칙하게 변경되는 경우 소스 보안 정책을 해제하는 것이 좋습니다.

각 플랫폼에 대한 액세스 예시

다음 예제에서는 SDK에 액세스하는 데 필요한 인터페이스를 소개하며, 전체 호출은 전체 코드 예제에서 확인할 수 있습니다.

• Android(운영 체제)

실행 환경: 안드로이드 4.1 이상 시스템 버전 프로젝트에 안드로이드 SDK를 도입합니다.

코드 예제

import com.xshield.jni.ShieldService; boolean succeed = ShieldService.Init("$AppID", " $AppKey "); // 초기화에 성공하면 true를 반환합니다.
String addr = ShieldService.GetTcpProxyAddr("test.com"); connect(addr); // 초기화에 성공하면 true를 반환합니다.
connect(addr);

이전 단계의 IP와 포트를 통해 연결을 설정하여 비즈니스 데이터를 송수신합니다(UI 스레드 방해를 방지하기 위해 초기화가 완료된 후 실행하는 것이 좋습니다).
UI 스레드 방해를 방지하기 위해 보안 프록시의 IP와 포트 가져오기
SDK를 초기화합니다(획득한 AppID 및 AppKey를 인터페이스에 전달).

• IOS

운영 환경iOS 8.0 이상에서는 앱 프로젝트에 IOS SDK를 추가합니다.

XCode를 사용하여 애플리케이션 프로젝트를 열고 프로젝트에 libxshield.a를 추가합니다.

코드 예제

XShieldIOS *sdk = [[XShieldIOS alloc] init];
[sdk init: @"$AppID " appKey: @" $AppKey "]; // 성공적인 초기화는 참을 반환합니다.
#포함 "xshield-ios.h"
NSString* addr = [sdk getTCPAddr:@"test.com"];
connect(addr);

이전 단계의 IP와 포트를 통해 연결을 설정하여 서비스 데이터를 주고받습니다.
보안 프록시의 IP와 포트를 가져옵니다(다음은 TCP 포워딩을 위해 구성된 도킹의 예입니다).
SDK를 초기화합니다(획득한 앱ID와 앱키를 인터페이스에 전달합니다).

통합 수락

클라이언트 측 패킷 캡처 분석을 통해 소스 IP가 노출되었는지 확인합니다. (핫스팟 네트워크를 공유할 수 있고 와이어샤크와 같은 패킷 캡처 소프트웨어를 설치할 수 있는 컴퓨터가 필요합니다). PC의 핫스팟을 공유하고(와이파이 핫스팟 소프트웨어 또는 시스템에 핫스팟 기능이 있는 경우) 휴대폰을 핫스팟 네트워크에 연결한 다음 패킷 캡처 소프트웨어를 열고 모든 서비스를 여러 번 테스트하여 서비스의 소스 IP가 캡처되는지 확인합니다. 소스 IP로 분석된 다른 도메인 이름이 있는지(있는 경우) 검토합니다.권장 운영 분리.
사업자는 실제 IP를 획득하기 위해 이용자의 실제 IP를 획득하는 것이 정상인지 확인하고, 고방어 노드의 IP를 획득하지 못한 경우 고방어 노드의 IP를 획득할 수 있습니다.IP 동일 기술 확인 가능.
라이브 출시 전 비즈니스 테스트, 라이브 출시 전에 더 많은 테스트를 수행하는 것이 좋으며, 그레이 스케일 테스트 2~3일 후 글로벌 업데이트가 가능합니다.

SDK 통합자주 묻는 질문

1. 포트 충돌 해결

수년간의 관찰과 통계 결과, 포트 충돌 문제는 개별 클라이언트 장치에서만 발생하며 발생 확률은 낮습니다. 하지만 문제를 완전히 해결하려면하지만 이 문제를 완전히 해결하려면 고급 기능을 사용하는 것이 좋습니다.

저희 SDK는 사용자가 구성한 '포워딩 규칙'에 따라 클라이언트 장치에서 적절한 포트를 열기 때문에 개별 클라이언트에서 포트 충돌이 발생할 확률이 매우 낮습니다.

포트 충돌에는 두 가지 유형이 있습니다:

• 시나리오 1: 구성한 포트가 개별 클라이언트의 다른 애플리케이션에 이미 점유되어 있어 사용자가 애플리케이션을 정상적으로 사용할 수 없습니다;

• 두 번째 시나리오: 동일한 인스턴스를 사용하는 여러 앱이 있고 사용자가 동일한 기기에서 여러 앱을 동시에 여는 경우, 사용자가 처음 여는 앱이 인스턴스의 모든 포트를 차지하고 두 번째 앱은 동시에 열 수 없는 포트에서 열리는 경우입니다.

이 문제는 PC에서는 두 번째 오픈 앱 비즈니스가 첫 번째 앱을 통해 sdk에 연결되기 때문에 두 번째 앱은 정상이지만 모바일에서는 두 번째 앱이 첫 번째 앱을 통해 sdk에 연결되기 때문에 처음에는 여전히 문제가 있으며, 사용자가 두 번째 앱을 사용할 때 첫 번째 앱이 백그라운드로 잘리고 잠시 후 첫 번째 앱이 정상입니다. 잠시 후 첫 번째 앱이 시스템에 의해 최대 절전 모드로 전환된 후 두 번째 앱이 연결되지 않을 수 있습니다.

이 문제에 대한 해결책은 아주 간단합니다.코드 절차는 다음과 같습니다.::

dunSetAutoChangePort(1);// 충돌 포트를 자동으로 변경하도록 설정, 한 번만 호출하면 됩니다.

int ret = clinkStart(key);//실드 시작, 일부 시스템은 다른 문서 보기 시작을 사용하며, 한 번만 호출하면 됩니다.

//새로운 연결의 경우 다음 코드 줄을 호출하여 새 포트를 가져옵니다.

int new_tcpPort = dunGetCurrentTCPPort("127.0.10.21", 600);//새 tcp 포트를 가져옵니다.

// 다음으로 new_tcpPort를 사용하여 애플리케이션에 연결합니다.

//connect("127.0.10.21", new_tcpPort) 예를 들어 이 의사 코드의 줄은 다음과 같습니다.

실드 통합 전 연결 connect("101.21.31.5",600)

쉴드 통합 후 연결 connect("127.0.10.21", dunGetCurrentTCPPort("127.0.10.21",600))

1.1 충돌하는 포트의 자동 교체 여부 설정하기

이 기능은호출은 쉴드스타트 호출 전에 이루어진 경우에만 유효합니다..

함수 프로토타입: void dunSetAutoChangePort(int val)

• 매개변수VAL: 자동 바꾸기 여부 0: 자동 바꾸기 없음, 1: 포트 충돌 시 새 포트로 자동 바꾸기.

• 기능val을 1로 설정하면 쉴드가 포트가 사용 중이거나 이 포트를 열 다른 이유가 없는 것을 감지하면 자동으로 사용 가능한 임의의 포트를 생성하고 이 임의의 포트를 원래 포트와 연결하여 프로그램에서 sdk에서 제공하는 dunGetCurrentTCPPort 또는 dunGetCurrentUDPPort 함수를 사용하여 새로 생성된 포트를 가져와서 연결에 사용할 수 있도록 합니다. 새로 생성된 포트를 가져오고 새 포트를 사용하여 연결하기 위해 sdk에서 제공하는 dunGetCurrentUDPPort 함수를 사용하면 포트 충돌 문제를 해결할 수 있습니다.

각 시스템에 해당하는 SDK 함수 정의는 다음과 같습니다.샘플 호출은 '데모 고급 함수'의 프로젝트를 참조하세요.::

Windows: 
외부 "C" CLINKAPI_API void dunSetAutoChangePort(int val).

안드로이드: 
클래스: cn.ay.clinkapi.

공용 네이티브 void dunSetAutoChangePort(int val).

IOS 정적 라이브러리: 
 클래스: ClinkAPI
void dunSetAutoChangePort(int val).

IOS 동적 라이브러리:
 외부 "C" void dunSetAutoChangePort(int val);.

Unity 
클래스: ClinkSDKForUnity
 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용

Uni-앱 
플러그인 이름: ayClinkApiForUni
플러그인 함수: dunSetAutoChangePort(val)

1.2현재 TCP 포트 가져오기

이전 포트에 포트 충돌이 있고 SDK가 다른 포트로 대체했을 수 있으므로 새 tcp 연결을 만들기 전에 이 함수를 호출하여 연결하려는 포트에 해당하는 새 포트를 가져와야 합니다.

• 함수 프로토타입: int dunGetCurrentTCPPort(const char* ip, int port)

• 매개변수IP: 포워딩 규칙의 클라이언트 연결 IP, 즉 127로 시작하는 IP port: 포워딩 규칙의 클라이언트 연결 포트, 즉 127로 시작하는 IP의 해당 포트

• 돌아오다(또는 가다)들어오는 포트에 충돌이 없거나 전달 규칙이 존재하지 않으면 반환되는 포트는 들어오는 포트와 동일하며, 충돌이 있는 경우 반환되는 포트는 변경 후 새 포트가 됩니다.

아래는 각 시스템에 해당하는 SDK 함수에 대한 정의입니다("데모 고급 기능"항목 입력:

Windows:
외부 "C" CLINKAPI_API int dunGetCurrentTCPPort(const char* ip, int port);

안드로이드:
클래스: cn.ay.clinkapi.
public native int dunGetCurrentTCPPort(String ip,int port);;

IOS 정적 라이브러리:
클래스: ClinkAPI
int dunGetCurrentTCPPort(const char* ip, int port);

IOS 동적 라이브러리:
외부 "C" void dunGetCurrentTCPPort(int val).

Unity
클래스: ClinkSDKForUnity
공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용 공용

Uni-앱
플러그인 이름: ayClinkApiForUni
플러그인 함수: dunGetCurrentTCPPort(ip,port)

1.3 현재 UDP 해당 포트 가져오기

이전 포트에 포트 충돌이 있을 수 있고 SDK가 다른 포트로 대체했을 수 있으므로 새 udp 연결을 만들기 전에 이 함수를 호출하여 연결하려는 포트에 해당하는 새 포트를 가져와야 합니다.

• 함수 프로토타입: int dunGetCurrentUDPPort(const char* ip, int port)
• 매개변수IP: 포워딩 규칙의 클라이언트 연결 IP, 즉 127로 시작하는 IP port: 포워딩 규칙의 클라이언트 연결 포트, 즉 127로 시작하는 IP의 해당 포트
• 돌아오다(또는 가다)새 포트를 가져오고, 들어오는 포트에 충돌이 없거나 포워딩 규칙이 존재하지 않으면 들어오는 포트와 동일한 포트를 반환하고, 충돌이 있으면 변경 후 새 포트를 반환합니다.

아래는 각 시스템에 해당하는 SDK 함수에 대한 정의입니다("데모 고급 기능"항목 입력:

Windows: 
외부 "C" CLINKAPI_API int dunGetCurrentUDPPort(const char* ip, int port);

안드로이드: 
클래스: cn.ay.clinkapi.
공용 네이티브 int dunGetCurrentUDPPort(String ip,int port);;

IOS 정적 라이브러리: 
 클래스: ClinkAPI
int dunGetCurrentUDPPort(const char* ip, int port);

IOS 동적 라이브러리: 
 외부 "C" void dunGetCurrentUDPPort(int val).

Unity 
클래스: ClinkSDKForUnity
 public static int dunGetCurrentUDPPort(문자열 ip, int port)

Uni-앱 
플러그인 이름: ayClinkApiForUni
플러그인 함수: dunGetCurrentUDPPort(ip,port)

2. 기타 기능

2.1 클라이언트 IP 얻기

클라이언트 측에서 클라이언트의 현재 IP를 가져오는 데 사용되며, 포워딩 규칙의 "IP 가져오기 방법"이 무엇으로 설정되어 있더라도 이 인터페이스는 여전히 유효하며 클라이언트 측이 가져오는 것이고 포워딩 규칙은 서버 측이 가져오는 것입니다.이 둘은 서로 관련이 없습니다.클라이언트의 IP는 호스트의 IP와 동일하지만 호스트의 IP는 클라이언트의 IP와 동일합니다.

예를 들어 사용자가 로그인할 때 로그인 정보를 클라이언트 IP와 함께 로그인 서버로 전송하여 백엔드 서버에서 여러 번 포워딩한 경우 클라이언트의 실제 IP를 가져올 수 있습니다.

• 함수 프로토타입: 긴 긴 dunGetClientIP()
• 반환: 부호화된 64비트 정수 IP 값, 다른 함수에 의해 문자열 IP로 변환 가능, 0 반환은 실드가 시작되지 않았거나 성공적으로 시작되지 않았음을 의미 정수 IP를 문자열 IP로 변환합니다. 알고리즘 코드는 다음과 같습니다.::

문자열 ipstr = ip / 256 / 256 / 256 % 256 + "." + ip / 256 / 256 % 256 + "." + ip / 256 / 256 % 256 + "." + ip % 256.

아래는 각 시스템에 해당하는 SDK 함수에 대한 정의입니다("데모 고급 기능"항목 입력:

Windows:
외부 "C" CLINKAPI_API 긴 긴 dunGetClientIP();

안드로이드:
클래스: cn.ay.clinkapi.
공용 네이티브 롱 dunGetClientIP();

IOS 정적 라이브러리:
클래스: ClinkAPI
긴 긴 dunGetClientIP();

IOS 동적 라이브러리:
외부 "C" 긴 긴 dunGetClientIP();

Unity
클래스: ClinkSDKForUnity
public static long dunGetClientIP()

Uni-앱
플러그인 이름: ayClinkApiForUni
플러그인 함수: dunGetClientIP()