Xcode를 이용하여 개발할 때 SDK v1을 포팅하는 방법과 빌드하는 방법을 안내합니다.

포팅하기

Hive SDK를 Xcode에 포팅하기 위해서는 iOS용 SDK v1이 필요합니다. SDK v1이 아직 없다면 다운로드 페이지에서 iOS용 SDK v1 패키지를 다운로드해 압축 해제하세요.

본 가이드는 Xcode 13.3.1 환경을 기준으로 안내합니다.

Swift 설정 추가하기

  1. Swift 프레임워크를 사용할 수 있도록 프로젝트 내에 dummy.swift 파일을 생성합니다.
  2. Bridging header는 Don’t Create 버튼을 클릭해 추가하지 않습니다.

만약 2번 항목이 발생하지 않거나 여전히 Swift 라이브러리를 인식하지 못한다면, 수동으로 Swift 설정을 진행해야 합니다.
관련 FAQ 내용을 참고하여 Swift 설정을 수동으로 추가합니다.

프레임워크 추가하기

SDK v1을 포팅하기 위해 추가해야 하는 프레임워크는 Xcode 내장 프레임워크, 서드 파티 프레임워크와 HiveSDK 프레임워크입니다.

프레임워크 설치하기

SDK v1.18.4부터 Hive SDK에서 사용하는 서드 파티 프레임워크를 CocoaPods로 설치할 수 있습니다.

  1. CocoaPods를 설치합니다.
  1. CocoaPods 설정 파일을 구성할 목적으로 Podfile을 생성합니다.
  1. 편집기에서 Podfile을 열어 SDK v1에 필요한 프레임워크를 추가합니다. 아래는 SDK v1 샘플에 포함 배포하는 Podfile 예제입니다.
  1. CocoaPods 설정에 따라 프레임워크를 설치합니다.

여러분의 Xcode 프로젝트에 추가해야 하는 프레임워크 상세 목록은 다음과 같습니다.

Xcode 내장 프레임워크서드 파티 프레임워크SDK v1 프레임워크
  • Accounts.framework
  • AdSupport.framework
  • AssetsLibrary.framework
  • CoreAudio.framework
  • CoreData.framework
  • CoreNetwork.framework
  • CoreSpotlight.framework
  • CoreTelephony.framework
  • CoreText.framework
  • Foundation.framework
  • iAd.framework
  • ImageIO.framework
  • libc++.dylib
  • libsqlite3.0.dylib
  • libz.tbd(또는 libz.a)
  • LocalAuthentication.framework
  • MediaPlayer.framework
  • MessageUI.framework
  • MobileCoreServices.framework
  • Photos.framework
  • SafariService.framework
  • Security.framework
  • Social.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UserNotification.framework (iOS 10 미만 지원 시 Optional)
  • WebKit.framework
  • AppTrackingTransparency.framework (1.19.0.3+ 시 추가. Optional)
  • TencentOpenAPI.framework
  • HiveSDK.framework
  • C2STracking.framework
  • HIVEPromotion.framework
  • HIVEProtocol.framework
  • HIVEIAPV4.framework
  • HIVECore.framework
  • HIVEBase.framework
  • HIVEUI.framework
  • HiveAppTrackingTransparency.framework (1.19.0.3+ 시 추가. Optional)

다음의 안내대로 위 목록의 프레임워크를 Xcode에 추가하세요.

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록 아래에서 추가하려는 대상 타겟을 선택하세요.
  3. Build Phase 탭을 클릭하세요.
  4. Link Binary With Libraries 항목을 클릭하세요.
  5. + 버튼을 클릭하세요.
  6. 추가할 프레임워크를 선택하는 창이 나타납니다. 추가해야 하는 프레임워크를 추가하세요.

라이브러리 추가하기

Hive를 포팅하기 위해서는 라이브러리가 필요합니다. 프레임워크 추가하기 단계에서 HiveSDK.framework를 추가했다면 libC2SHub2_iphoneos.a, libC2SHub2_iphoneosd.a, libC2SHub2_iphonesimulator.a, libC2SHub2_iphonesimulatord.a 파일은 추가 항목에서 제외하세요.

  1. Xcode의 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Build Settings 탭을 클릭하세요.
  4. Search Paths 항목을 클릭하고 라이브러리 파일의 폴더를 Library Search Paths에 마우스로 끌어서 놓습니다(drag-and-drop).

* libC2SModule_iphoneos.a
* libC2SModule_iphoneosd.a
* libC2SModule_iphonesimulator.a
* libC2SModule_iphonesimulatord.a

리소스 추가하기

C2SActiveUserResource.bundle, MercuryResources.bundle, HiveSocialResources.bundle, C2SHIVEPromotionResource.bundle, HiveAdultAuthorizationBundle.bundle, HIVEIAPV4Resource.bundle 파일을 끌어다 Xcode 프로젝트에 추가(drag-and-drop)하세요. 번들 파일은 개발자 사이트에서 다운로드한 Hive SDK 패키지 resource 디렉토리 내에 위치합니다. 번들 파일을 추가한 후 Build Phase 탭의 Copy Bundle Resources 섹션에 번들 파일이 추가되어 있는지 확인하세요. 추가되어 있지 않다면, 다음의 작업을 수행하세요.

  1. Xcode의 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Build Phase 탭을 클릭하세요.
  4. Copy Bundle Resources 항목을 클릭하세요.
  5. + 버튼을 클릭하여 HIVE_SDK_resource.bundle 파일을 추가하세요.

헤더파일 추가하기

Hive를 포팅하기 위해 헤더파일을 준비하여야 합니다. 필요한 헤더파일은 아래와 같습니다. 준비된 헤더파일이 위치한 폴더 경로를 Header Search Paths에 추가해야 합니다. 폴더 경로가 추가되어 있지 않다면 다음의 작업을 수행하세요.

  1. Xcode의 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Build Settings 탭을 클릭하세요.
  4. Search Paths 항목을 클릭하고 헤더 파일의 폴더를 Header Search Paths에 마우스로 끌어서 놓습니다(drag-and-drop).

* include/C2SAppDelegate.h
* include/C2SModule.h
* include/C2SModuleApi.h
* include/C2SModuleArgKey.h
* include/C2SModuleErrorCode.h
* include/iOS/Module_iOS.h
* include/iOS/ModuleHelper_iOS.h

일반 설정하기

안내에 따라 다음의 항목을 설정하세요.

앱 상태 바 노출 설정하기

앱에 상태 바를 노출하지 않기 위해 View Controller-Based Status Bar Appearance 필드 값을 NO로 설정하세요.

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Info 탭을 클릭하세요.
  4. Info 탭에 View Controller-Based Status Bar Appearance 필드 존재 여부에 따라 다음의 작업을 수행하세요.

* 필드가 있다면 필드를 선택하여 값을 NO로 설정하세요.

* 필드가 없다면, 필드를 추가하세요.
1. Info 탭 목록에서 마우스 오른쪽 버튼을 클릭하세요.
2. Add Row 메뉴를 클릭하세요.
3. Key 항목에 View Controller-Based Status Bar Appearance를 입력하세요.
4. Type 항목을 Boolean로 설정하세요.
5. Value 항목을 NO로 설정하세요.

화이트 리스트 추가하기
Facebook

Facebook Scheme을 화이트 리스트에 추가하려면 프로젝트 창을 이용하거나 Info.plist 파일에 코드를 직접 추가하는 방법이 있습니다.

iOS 9부터, 외부 앱으로 전환 시 화이트 리스트에 추가된 Scheme에 대해서만 전환이 허용됩니다. iOS 9 환경에서 유저가 여러분의 게임에서 Facebook으로 로그인 할 때 Hive는 사파리 뷰 컨트롤러를 활용하여, 사파리 웹뷰로 Facebook 로그인을 진행시킵니다. 때문에, 게임 앱에서 Facebook 앱으로의 전환이 발생하지 않고 앱 내부의 브라우저를 이용하여 로그인을 처리할 수 있습니다.
Facebook은 화이트 리스트에 Facebook Scheme을 기본적으로 등록하도록 권장하고 있습니다. Facebook SDK 문서 보기

프로젝트 창에서 수정하기

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Info 탭을 클릭하세요.
  4. Info 탭의 LSApplicationQueriesSchemes 클릭하고 + 버튼을 클릭하여 다음의 네 개 Scheme을 추가하세요.

* fbapi
* fbauth2
* fb-messenger-api
* fbshareextension

Info.plist 직접 수정하기

Info.plist에 아래 코드를 직접 추가하는 방법도 있습니다.

QQ

QQ Scheme을 화이트 리스트에 추가하려면 프로젝트 창을 이용하거나 Info.plist 파일에 코드를 직접 추가하는 방법이 있습니다.

프로젝트 창에서 수정하기

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Info 탭을 클릭하세요.
  4. Info 탭의 LSApplicationQueriesSchemes 클릭하고 + 버튼을 클릭하여 다음의 여섯 개 Scheme을 추가하세요.

* mqqOpensdkSSoLogin
* mqqopensdkapiV2
* mqqopensdkapiV3
* wtloginmqq2
* mqq
* mqqapi

Info.plist 직접 수정하기

Info.plist에 아래 코드를 직접 추가하는 방법도 있습니다.

접근 권한 요청 설정하기

카메라, 연락처 및 사진첩에 대한 접근 권한을 얻기 위해 Info.plist에 키를 추가하세요.

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Info 탭을 클릭하세요.
  4. Info 탭의 Custom iOS Target Properties 항목을 클릭하세요.
  5. Custom iOS Target Properties 목록에서 마우스 오른쪽 버튼을 클릭하세요.
  6. Add Row 메뉴를 클릭하세요.
  7. Key 항목에 NSCameraUsageDescription을 입력하고, Value 항목은 다국어 설정 파일 > Base.Iproj 폴더 > InfoPlist.strings에 명시된 값을 추가합니다.

* 다국어 설정 파일에 명시된 게임 유저에게 권한 승인을 요청하는 메시지를 작성하세요. 권한 승인 요청 팝업 메시지를 입력하지 않으면 사용중인 사용자 접근 권한에 대한 추가 설명 가이드가 누락되어 앱 검수 시 거부(Reject)됩니다.
* Hive SDK v1.19.0.3에서 업데이트된 Permission.strings 파일을 적용한다면 해당 파일도 반드시 변경해야 합니다. 그렇지 않으면 앱스토어 업로드 단계에서 여러분의 앱이 거부(Reject)될 수 있습니다.
8. NSPhotoLibraryUsageDescription, NSUserTrackingUsageDescription 키도 6번-7번 과정을 반복하세요.
NSPhotoLibraryUsageDescription, NSCameraUsageDescription, NSUserTrackingUsageDescription 키의 대응 값은 Apple의 법적 요구 사항 가이드라인에 따라 권한 사용 목적을 알리고, 유저가 허용했을 때만 사용할 수 있도록 해야 합니다. 다국어 설정 파일은 연락처, 카메라, 사진첩, IDFA 사용 권한이 필요할 때 유저에게 요청 목적에 대해 알리고 사용을 허용할 수 있도록 팝업 문구를 언어별로 제공합니다. IDFA권한은 Hive SDK 초기화시 요청 팝업이 생성되며, CAMERA와 PHOTO 권한은 실제 사용 시점에 권한 요청 팝업이 생성되고 PUSH는 SDK를 초기화할 때 요청됩니다. 네 항목 모두 선택 권한으로, 유저가 거부한다고 해도 게임 플레이에는 문제가 없습니다.

알림 설정하기

푸시 알림 설정을 활성화하지 않으면 iOS 10 기기에서 푸시 토큰이 발급되지 않으며, 앱 검수 시 ‘Missing Push Notification Entitlement’라는 사유로 앱이 거부될 수 있습니다. 다음의 안내에 따라 푸시 알림을 설정하세요.

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Signing & Capabilities 탭을 클릭하세요.
  4. Signing & Capabilities 탭의 좌측 상단에 있는 + Capability 버튼을 클릭하세요.
  5. 목록에서 Push Notification을 선택해 추가합니다.
  6. Signing & Capabilities 목록에 추가된 Push Notification을 확인할 수 있습니다.
  7. 긴급한 알림 기능을 사용하려면 Capabilities 목록에 추가된 Time Sensitive Notifications 항목을 ON 시키세요. (기능 및 사용법 안내)

– Time Sensitive Notifications는 iOS 15 이상에서 사용 가능한 기능으로, 유저가 긴급한 알림을 활성화한 앱의 리모트 푸시를 받을 수 있습니다.

결제 설정하기

앱에서 결제 기능을 사용하려면 In-App Purchase Capability를 활성화해야 합니다. 다음의 안내에 따라 In-App Purchase 알림을 설정하세요.

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Signing & Capabilities 탭을 클릭하세요.
  4. Signing & Capabilities 탭의 좌측 상단에 있는 + Capability 버튼을 클릭하세요.
  5. 목록에서 In-App Purchase을 선택해 추가합니다.
  6. Signing & Capabilities 목록에 추가된 In-App Purchase를 확인할 수 있습니다.
IdP 목록에 Apple로 로그인 추가하기

iOS 13 기기에서 사용할 수 있는 Apple로 로그인을 IdP 목록에 추가합니다. 신규 IdP는 Xcode 11.0 이상 버전에서 추가할 수 있습니다. 다음의 안내에 따라 신규 IdP를 추가하세요.

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.

  2. TARGETS 목록에서 여러분의 앱을 선택하세요.

  3. Signing & Capabilities 탭을 클릭하세요.

  4. Signing & Capabilities 탭 좌측 상단에 있는 + Capability 버튼을 클릭하세요.

  5. 목록에서 Sign In with Apple을 선택해 추가합니다.

  6. Signing & Capabilities 목록에 추가된 Sign In with Apple을 확인할 수 있습니다.

Apple로 로그인 기능을 구현한 후 IdP 연동 상태 정보에도 반드시 추가해야 합니다.

  • 권한이나 기타 문제로 Capability 목록에 보이지 않을 경우에는 Apple 개발자 콘솔에서 Sign In with Apple 항목을 활성화하세요. 이후 갱신된 프로비저닝이 적용되면 4~6 순서를 다시 진행해 IdP를 추가합니다.
KeyChain 설정하기

Hive SDK는 iOS타겟에서 KeyChain을 사용하고 있습니다. KeyChain-GroupSharing 기능을 사용하지 않는 경우는 특별한 추가 설정이 필요 없습니다.

Hive 설정하기

Hive 사용을 위한 설정 작업은 Xcode에서 설정 항목들을 설정하는 작업이 있습니다. 다음의 안내에 따라 Hive 설정 작업을 수행하세요.

Xcode에서 Hive 값 설정하기

Facebook, 딥링크를 사용하려면 Xcode에 Hive 값을 설정해야 합니다. 다음의 안내에 따라 수행하세요.

Facebook 설정

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Info 탭을 클릭하세요.
  4. Info 탭 안의 Custom iOS Target Properties 항목을 클릭하고 FacebookDisplayName 속성에 앱에서 노출하고자 하는 앱 타이틀을 입력하세요.
  5. Info 탭 안의 URL Types 항목을 클릭한 후 + 아이콘을 클릭하여 Additional url type properties 항목을 생성하세요.
  6. Additional url type properties 항목 URL Schemes 란에 fb를 덧붙인 Facebook AppID를 입력하세요.
    예. fb012342478841523
  7. Info 탭 안의 Custom iOS Target Properties 항목을 클릭하고 FacebookAutoInitEnabled, FacebookAutoLogAppEventsEnabled, FacebookAdvertiserIDCollectionEnabled 속성을 추가 후 NO로 설정하세요.
    상세한 설정은 Hive SDK v1 Facebook 설정 가이드에서 확인할 수 있습니다.

Google 설정

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. GoogleService-Info.plist 파일을 프로젝트에 추가하세요.
  3. TARGETS 목록에서 여러분의 앱을 선택하세요.
  4. Info 탭을 클릭하세요.
  5. Info 탭 안의 URL Types 항목을 클릭한 후 + 아이콘을 클릭하여 Additional url type properties 항목을 생성하세요.
  6. Additional url type properties 항목 아래 URL Schemes 필드에 Identifier는 공백 처리, URL Schemes는 reversed client ID를 입력하세요.

QQ 설정

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Info 탭을 클릭하세요.
  4. Info 탭 안의 Custom iOS Target Properties 항목을 클릭하고 QQAppId 속성에 QQ App ID를 입력하세요.
  5. Additional url type properties 항목 아래 URL Schemes 필드에 Identifier는 공백 처리, URL Schemes는 tencent{QQ App ID}를 입력하세요.
    예. tencent1106227203

딥링크 설정

  1. Xcode 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Info 탭을 클릭하세요.
  4. Info 탭 안의 URL Types 항목을 클릭하세요.
  5. + 아이콘을 클릭하여 Additional url type properties 항목을 생성하세요.
  6. Additional url type properties 항목 아래 Identifier 필드와 URL Schemes 필드에 여러분의 AppID를 입력하세요.

AppDelegate 적용하기

다음 코드와 같이 AppDelegate.m 파일의 API에서 개별모듈이 제공하는 API를 호출하세요.

 

빌드하기

빌드 설정하기

  1. Xcode의 프로젝트 창의 프로젝트 네비게이터에서 여러분의 프로젝트를 선택하세요.
  2. TARGETS 목록에서 여러분의 앱을 선택하세요.
  3. Build Settings 탭을 클릭하세요.
  4. Linking 항목을 클릭하고 Other Linker Flags 필드에 아래 값을 입력하세요.

* Debug
* -ObjC
* -lC2SModule_$(PLATFORM_NAME)d
* Release
* -ObjC
* -lC2SModule_$(PLATFORM_NAME)
5. Search Paths 항목을 클릭하고 Hive SDK의 framework 폴더를 Framework Search Paths에 마우스로 끌어서 놓습니다(drag-and-drop).

빌드하기

iOS 앱을 빌드하는 일반적인 방법으로 앱을 빌드하세요.

납품용 빌드 시에는 앱을 .ipa 파일로 전달하세요.

 

앱 업로드하기

App Store에 업로드하기

Apple App Store Connect에 여러분의 앱을 업로드하는 방법은 세 가지입니다. Xcode에서 앱을 직접 업로드하거나 altool을 실행해 업로드하는 방법, 혹은 Transporter를 이용하는 방법이 있습니다.

업로드 도구 선택

Apple 가이드에서 확인하기

    • Xcode에서 직접 업로드
      Xcode 11을 기준으로, 완성한 앱을 선택한 후 Distribute App 버튼을 클릭하면 App Store 버전 또는 Ad Hoc 버전을 직접 업로드하거나 업로드할 .ipa파일을 생성할 수 있습니다. GUI를 이용하는 일반적인 권장 방법입니다.

  • altool
    Xcode에 포함된 명령어 라인 도구 altool은 /Applications/Xcode.app/Contents/Developer/usr/bin/altool에 위치합니다. Jenkins 같이 자동화된 빌드 시스템을 이용할 경우 권장하는 방법입니다. 빌드 산출물은 명령어 라인 형태로, 유효성 검사는 물론 업로드까지 바로 진행할 수 있습니다. AppCenter(구. HockeyApp)를 지원하는 기능입니다.
  • Transporter
    iTunes Store나 App Store에 컨텐츠를 업로드하는 가장 쉬운 방법입니다. 여러분의 앱뿐만 아니라 앱 내 컨텐츠, 예를 들어 동영상이나 e-Book, 음악 등 재생 가능한 컨텐츠 또한 업로드할 수 있습니다.

 

Xcode에서 직접 업로드

Apple 가이드에서 확인하기

  1. Xcode Organizer를 실행합니다. Xcode Organizer는 Xcode 메뉴에서 실행하거나, Archive 작업 실행 후 자동으로 팝업합니다.
  2. Distribute App 버튼을 클릭해 업로드를 준비합니다. 배포 버전의 타겟에 따라 배포 방법을 선택 할 수 있습니다.
  3. 배포 방법을 선택합니다. Xcode를 이용해 AppStore Connect에 직접 업로드하는 방식과 파일로 추출해 업로드하는 방식 중 선택 가능합니다.
  4. 배포 옵션을 선택합니다. 배포 버전을 생성할 때 옵션을 조정할 수 있습니다.

* App Thinning: 배포 타겟별 리소스를 분리하여 용량을 줄이는 기능입니다.
* Rebuild from Bitcode: Bitcode 기능을 활성화하여 앱 업데이트 시 업데이트 변경점을 최소화하는 기능입니다.
* Include manifest for over-the-air installation: Ad Hoc/Development 빌드일 경우 App Store 외부에서 다운로드/설치할 수 있도록 manifest 파일을 첨부하는 기능입니다.

  • Strip Swift symbols: 사용하지 않는 Swift 심볼 파일을 제거해 앱 용량을 줄이는 기능입니다.
  • Upload your app’s symbols to receive symbolicated reports from Apple: 디버그 심볼을 추출해 업로드한 후 Apple이 전송하는 리포트를 수신할 때 심볼과 연결된 형태로 받을 수 있도록 지원하는 기능입니다.

 

  • 배포 빌드에 서명을 추가합니다.
    배포 버전에 서명을 추가하면 최종 버전이라는 것을 유저에게 보장합니다. Ad Hoc, App Store 혹은 Development 빌드를 선택하여 배포 빌드에 서명할 수 있습니다. 빌드에 필요한 인증서를 선택한 후 추출된 파일을 저장하거나 업로드합니다. 파일로 추출한 경우에는 해당 .ipa 파일을 Transporter 앱을 이용해 업로드합니다.

 

altool로 업로드

명령어 라인으로 상황에 맞는 업로드를 명령할 수 있습니다. 도구 이용 방법을 자세히 확인하려면 아래 링크별 지침을 읽어보세요.

Transporter로 업로드

별도 가이드를 제공하지 않습니다. Apple에서 제공하는 가이드를 참고해 수행하세요.