# 연동하기

이 문서는 Adbrix Unity SDK를 앱에 통합하는 방법을 다룹니다. Adbrix SDK를 설치하면 이벤트 분석 기능이 제공됩니다.

더 자세히 알아보려면 [리소스 및 샘플](https://adbrix.gitbook.io/developer-guide/common/resource-and-sample)을 참조하세요.

## 시작하기 전에

### 앱 생성

[Adbrix 콘솔](https://console.adbrix.ai/)의 `앱 설정/앱 정보` 페이지에서 앱을 생성하여 SDK 초기화에 필요한 **Application Key**와 **Secret Key**를 발급받아 주십시오.

![앱 정보](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-6228fd98bac706c18facda8b3b9116f69ff3f57d%2Fappinfo.png?alt=media)

### 지원 정보

#### Android

* 최소 지원 SDK : Android 4.4+ / API 19+
* 대상 SDK : 33

#### iOS

* iOS 12.0
* Xcode 16.0

### 의존성

#### Android

* [com.android.installreferrer:installreferrer:2.2](https://mvnrepository.com/artifact/com.android.installreferrer/installreferrer)
* [com.google.android.gms:play-services-ads-identifier:18.0.1](https://mvnrepository.com/artifact/com.google.android.gms/play-services-ads-identifier)

## SDK 설치

{% tabs %}
{% tab title="PackageManager 사용" %}
**PackageManager를 사용하여 SDK 및 의존성 추가하기**

**1. `Windows > Package Manager` 창을 엽니다.**

![Package Manager 클릭하기](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-5902d20ebbf1c767c595df45d5f14aa6418ef452%2Fpackage_manager_1.png?alt=media)

**2. 좌측 상단의 `+` 아이콘을 클릭합니다.**

**3. `Install package from git url...`를 클릭합니다.**

![Install package from git url 클릭하기](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-043290aa5e50f39764db8a36139f9ab1785d32f0%2Fpackage_manager_2.png?alt=media)

**4. `https://github.com/IGAWorksDev/adbrix-unity-sdk.git`를 복사 붙여넣기 한 다음 우측의`install`를 클릭합니다.**

```
https://github.com/IGAWorksDev/adbrix-unity-sdk.git
```

![URL 입력](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-c8b1c1b92f5180802fa99ccbcbbe4160cfb07438%2Fpackage_manager_3.png?alt=media)

**5. SDK 추가가 완료되었습니다.**

**6. 이어서 External Dependency Manager for Unity가 요구하는** [**가이드**](https://github.com/googlesamples/unity-jar-resolver?tab=readme-ov-file#getting-started)**에 따라 External Dependency Manager for Unity 플러그인을 프로젝트에 추가합니다.**

> [External Dependency Manager for Unity](https://github.com/googlesamples/unity-jar-resolver)는 의존성을 추가하기 위해 사용하는 Unity Plugin입니다.

**7. SDK 의존성 추가가 완료되었습니다.**
{% endtab %}

{% tab title="Unity Package 사용" %}
**Adbrix Unity Package를 사용하여 SDK 추가하기**

Adbrix [Unity Package](https://docs.unity3d.com/Manual/AssetPackages.html)는 Android와 iOS SDK를 감싸서 사용하기 용이한 C# 인터페이스를 제공합니다.

**1.** [**Release의 Assets**](https://github.com/IGAWorksDev/adbrix-unity-sdk/releases)**에서 Adbrix Unity Package 다운로드 합니다.**

**2. 패키지를 import 하기**

Unity 에디터에서 `Assets > Import Package > Custom Package`로 이동하여 패키지를 Unity 프로젝트로 가져옵니다. 그런 다음 "Import"를 클릭합니다.

또는 Unity 애셋 패키지 가져오기 지침을 따라 커스텀 Unity 패키지를 가져오는 방법에 대한 자세한 [가이드](https://docs.unity3d.com/Manual/AssetPackages.html)를 확인하세요.

**3. SDK 추가가 완료되었습니다. 만약 EDM4U를 사용하지 않는 경우 아래의 단계를 추가해주세요.**

**4.** [**Release**](https://github.com/IGAWorksDev/adbrix-unity-sdk/releases/) **페이지의 Assets에서 사용하려는 버전의 Adbrix SDK Android Archive package(.aar) 파일, iOS xcframework를 다운로드 합니다.**

```
adbrix-android-sdk-[SDK-VERSION].aar
adbrix-unity-extension-[EXTENSION-VERSION].aar
AdbrixSDK.xcframework.zip
```

**4. `Assets/Plugins/Android/` 경로에 다운로드한 Adbrix SDK Android Archive package(.aar) 파일을 추가합니다.**

**5. `Assets/Plugins/Android/` 경로에 다음의 SDK가 필요로 하는 의존성을 추가합니다.**

{% hint style="warning" %}
추가 하려는 라이브러리에 종속되는 의존성이 있을 경우 해당 파일을 모두 추가해야 합니다.
{% endhint %}

* [com.android.installreferrer:installreferrer](https://developer.android.com/google/play/installreferrer/library)
* [com.google.android.gms:play-services-ads-identifier](https://developers.google.com/android/guides/setup)

**6. iOS 프로젝트를 빌드 후 Xcode에 다운받은 xcframework 의존성을 추가합니다.**

Targets / Unity-iPhone / General / Frameworks, Libraries, and Embedded Content 에 AdbrixSDK.xcframework 를 추가합니다.

Targets / UnityFramework / General / Frameworks and Libraries 에 AdbrixSDK.xcframework를 추가합니다.

**7. SDK 의존성 추가가 완료되었습니다.**
{% endtab %}
{% endtabs %}

### SDK 설정하기

{% tabs %}
{% tab title="Android" %}
**`AndroidManifest.xml` 설정하기**

{% hint style="info" %}
`AndroidManifest.xml` 파일이 없을 경우 Unity 에디터에서 `File > Build Profiles > Android > Publishing Settings > Custom Main Manifest`를 체크하여 생성이 가능합니다.
{% endhint %}

Adbrix를 사용하기 위해서는 `Assets/Plugins/Android/` 경로에 있는 `AndroidManifest.xml`의 수정이 필요합니다. 다음의 필요한 사항을 확인하여 수정하여 주시기 바랍니다.

**1. `<manifest>` 내에 다음의 권한을 추가해주세요.**

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" /><!-- 구글 광고 ID를 수집해야할 경우 추가합니다. -->
```

**2. `<application>` 내에 다음의 `com.igaworks.adbrix.unity.AdbrixUnityInitProvider`를 추가해주세요.**

{% hint style="danger" %}
`android:authorities`는 다른 패키지와 겹치지 않도록 고유한 이름을 사용해야합니다.
{% endhint %}

```xml
<provider android:authorities="${applicationId}.adbrix.unity.INIT_PROVIDER" android:name="com.igaworks.adbrix.unity.AdbrixUnityInitProvider" android:exported="false" />
```

**3. 설정이 완료되었습니다.**

다음은 작성이 완료된 예시입니다.

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.unity3d.player" xmlns:tools="http://schemas.android.com/tools">
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
  <application>
    <activity android:name="com.unity3d.player.UnityPlayerActivity" android:theme="@style/UnityThemeSelector" android:exported="true">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
      <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
    </activity>
    <provider android:authorities="${applicationId}.adbrix.unity.INIT_PROVIDER" android:name="com.igaworks.adbrix.unity.AdbrixUnityInitProvider" android:exported="false" />
  </application>
</manifest>
```

{% endtab %}
{% endtabs %}

## SDK 초기화

### 초기화 하기

앱에서 Adbrix SDK를 초기화하려면 다음 단계를 완료하세요.

{% tabs %}
{% tab title="`AdbrixUnitySettings.asset`를 사용" %}
`AdbrixUnitySettings.asset`은 Unity 에디터 상에서 편리하게 SDK의 설정을 할 수있게 도와주며, SDK의 안정적인 초기화를 보장합니다.

**1. `AdbrixUnitySettings.asset` 생성하기.**

Unity Editor에서 `Assets > Adbrix > Settings`를 눌러 `AdbrixUnitySettings.asset`를 생성합니다.\
이 파일은 프로젝트의 `Assets/Adbrix/Resources`에 생성됩니다.

**2. Application KEY와 SECRET KEY를 입력하고 필요한 설정을 적용합니다.**

{% hint style="info" %}
Application KEY와 SECRET KEY는 [Adbrix Console](https://console.adbrix.ai/)의 `앱 설정 > 앱 정보`에서 확인이 가능합니다.
{% endhint %}

![AdbrixUnitySettings.asset](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-36a68e6c9b350804ab9e5f0b9f16fd1f75eb0425%2Fadbrixunitysettings.png?alt=media)

{% hint style="info" %}
구글 광고 ID를 수집해야할 경우`Collect Google Advertising Id`를 체크 해야합니다.
{% endhint %}

**3. 초기화가 완료되었습니다.**
{% endtab %}

{% tab title="C# 스크립트에서 초기화 하기" %}
**1. Adbrix를 사용할 GameObject에 스크립트를 등록합니다.**

**2. 스크립트에 Adbrix를 추가합니다.**

```csharp
using AdbrixPlugin;
```

**3. `Awake()` 내에 다음 코드를 작성합니다.**

{% hint style="info" %}
Application KEY와 SECRET KEY는 [Adbrix Console](https://console.adbrix.ai/)의 `앱 설정 > 앱 정보`에서 확인이 가능합니다.
{% endhint %}

```csharp
public void Awake() {
    Dictionary<string, object> config = new Dictionary<string, object> {
        {ABConfig.IOS_LOG_ENABLE, true},
        {ABConfig.ANDROID_LOG_ENABLE, true},
        {ABConfig.ANDROID_LOG_LEVEL, ABAndroidLogLevel.VERBOSE},
        {ABConfig.ANDROID_COLLECT_GOOGLE_ADVERTISING_ID, true} //구글 광고 ID를 수집해야할 경우 true로 적용합니다.
    };
    Adbrix.InitWithConfig("{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config);
}
```

**4. 초기화가 완료되었습니다.**
{% endtab %}
{% endtabs %}

### 구글 광고 ID 설정하기 <a href="#set_collect_google_advertising_id" id="set_collect_google_advertising_id"></a>

Google 광고 ID를 수집하기 위해선 Config의 `ANDROID_COLLECT_GOOGLE_ADVERTISING_ID`를 **true**로 설정하여 수집 여부를 설정해야합니다. 만약 Google 광고ID를 수집하지 않아야 한다면, [구글 광고 ID 수집 여부 변경하기](#change_collect_google_advertising_id)를 통해 수집하지 않도록 설정할 수 있습니다.

{% tabs %}
{% tab title="`AdbrixUnitySettings.asset` 사용" %}
Android Settings의 `Collect Google Advertising ID`를 체크합니다.

![AdbrixUnitySettings.asset](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-36a68e6c9b350804ab9e5f0b9f16fd1f75eb0425%2Fadbrixunitysettings.png?alt=media)
{% endtab %}

{% tab title="C# 스크립트에서 호출" %}
**`Awake()` 내에 다음 코드를 작성합니다.**

```csharp
using AdbrixPlugin;
public void Awake() {
    Dictionary<string, object> config = new Dictionary<string, object> {
        {ABConfig.ANDROID_COLLECT_GOOGLE_ADVERTISING_ID, true} //구글 광고 ID를 수집해야할 경우 true로 적용합니다.
    };
    Adbrix.InitWithConfig("{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config);
}
```

{% endtab %}
{% endtabs %}

## 딥링크 오픈 분석

Adbrix Unity SDK에서는 딥링크를 분석하는 추가 코드 작업이 필요하지 않습니다. SDK에서 자동으로 처리하여 딥링크 오픈 분석이 가능합니다.

{% hint style="info" %}
Unity에 딥링크를 연동하는 방법은 Unity에서 제공하는 [딥링크 메뉴얼](https://docs.unity3d.com/kr/2023.2/Manual/deep-linking.html)을 참고하여 주시기 바랍니다
{% endhint %}

### 지연된 딥 링크 핸들링하기(선택사항)

SDK는 앱이 설치되지 않은 유저가 링크를 클릭 후 앱을 설치했을때 자동으로 딥 링크를 실행합니다. 직접 지연된 딥 링크를 핸들링 하려면 다음 메소드를 호출하여 자동 딥링크 실행을 막을 수 있습니다.

{% tabs %}
{% tab title="`AdbrixUnitySettings.asset`를 사용" %}
**1. `Is Block Deferred DeepLink Launch`를 체크합니다.**

![AdbrixUnitySettings.asset](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-36a68e6c9b350804ab9e5f0b9f16fd1f75eb0425%2Fadbrixunitysettings.png?alt=media)

**2. 스크립트에 `AdbrixDeepLinkCallback`을 implement 합니다.**

```csharp
using AdbrixPlugin;
public class MainHandler : MonoBehaviour, AdbrixDeepLinkCallback
{
    public void OnAdbrixDeepLink(AdbrixDeepLink adbrixDeepLink)
    {
        UnityEngine.Debug.Log("OnAdbrixDeepLink() deepLink : "+adbrixDeepLink.deepLink);
    }
}
```

**3. 완료 되었습니다.**

SDK가 지연된 딥링크를 전달 받을때 딥링크로 이동하지 않는 대신 `void OnAdbrixDeepLink(AdbrixDeepLink adbrixDeepLink)`로 이벤트를 전달합니다.
{% endtab %}

{% tab title="C# 스크립트에서 호출" %}
**1. 스크립트에 `AdbrixDeepLinkCallback`을 implement 합니다.**

```csharp
using AdbrixPlugin;
public class MainHandler : MonoBehaviour, AdbrixDeepLinkCallback
{
    public void OnAdbrixDeepLink(AdbrixDeepLink adbrixDeepLink)
    {
        UnityEngine.Debug.Log("OnAdbrixDeepLink() deepLink : "+adbrixDeepLink.deepLink);
    }
}
```

**2. `Awake()`에서 다음 코드를 작성합니다.**

```csharp
public void Awake() 
{
    Adbrix.BlockDeferredDeepLinkLaunch(this);
}
```

**3. 완료 되었습니다.**

SDK가 지연된 딥링크를 전달 받을때 딥링크로 이동하지 않는 대신 `void OnAdbrixDeepLink(AdbrixDeepLink adbrixDeepLink)`로 이벤트를 전달합니다.
{% endtab %}
{% endtabs %}

**AdbrixDeepLink**

**result: int**

지연된 딥링크 처리 결과 입니다. ABDeepLinkResult 클래스로 해당 결과 값의 의미를 파악할수있습니다.

```csharp
UnityEngine.Debug.Log("OnAdbrixDeepLink() result: "+ABDeepLinkResult.GetResult(adbrixDeepLink.result));
```

* 결과 값 의미
  * 0 : `PROCESSED`
  * 1 : `ORGANIC`
  * 2 : `TRACKING_LINK_SETTINGS_INCORRECTLY`
  * 3 : `ORGANIC_NCPI_IN_PROCESS`
  * -1 : `NO_CONVERSION`

**deepLink : string**

지연된 딥링크 값입니다.

```csharp
UnityEngine.Debug.Log("OnAdbrixDeepLink() deepLink: "+ABDeepLinkResult.GetResult(adbrixDeepLink.deepLink));
```

## SDK 설정

SDK 초기화 시에 로그 활성화 등의 옵션을 설정할 수 있습니다.

### 로그 활성화 하기

{% tabs %}
{% tab title="`AdbrixUnitySettings.asset`를 사용" %}
플랫폼에 따라 `Android Log Enabled` 혹은 `Ios Log Enabled`를 체크합니다.

![AdbrixUnitySettings.asset](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-36a68e6c9b350804ab9e5f0b9f16fd1f75eb0425%2Fadbrixunitysettings.png?alt=media)
{% endtab %}

{% tab title="C# 스크립트에서 호출" %}
플랫폼에 따라 `ABConfig.IOS_LOG_ENABLE` 혹은 `ABConfig.ANDROID_LOG_ENABLE`를 사용합니다.

```csharp
Dictionary<string, object> config = new Dictionary<string, object> {
    {ABConfig.IOS_LOG_ENABLE, true},
    {ABConfig.ANDROID_LOG_ENABLE, true},
};
Adbrix.InitWithConfig("{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config);
```

{% endtab %}
{% endtabs %}

### 로그 레벨 변경하기

다음의 방법을 통해 Android의 표시 로그 레벨을 변경할 수 있습니다.

{% hint style="info" %}
로그 레벨 값은 [`android.util.Log`](https://developer.android.com/reference/android/util/Log#constants_1)의 상수 값의 정의를 따릅니다.
{% endhint %}

{% tabs %}
{% tab title="`AdbrixUnitySettings.asset`를 사용" %}
`Android Log Level`에서 원하는 레벨을 설정합니다.

![AdbrixUnitySettings.asset](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-36a68e6c9b350804ab9e5f0b9f16fd1f75eb0425%2Fadbrixunitysettings.png?alt=media)
{% endtab %}

{% tab title="C# 스크립트에서 호출" %}

```csharp
Dictionary<string, object> config = new Dictionary<string, object> {
    {ABConfig.ANDROID_LOG_LEVEL, ABAndroidLogLevel.VERBOSE},
};
Adbrix.InitWithConfig("{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config);
```

{% endtab %}
{% endtabs %}

* ABAndroidLogLevel
  * VERBOSE : `2`
  * DEBUG : `3`
  * INFO : `4`
  * WARN : `5`
  * WARN : `6`
  * ASSERT : `7`

### 구글 광고 ID 수집 여부 변경하기 <a href="#change_collect_google_advertising_id" id="change_collect_google_advertising_id"></a>

{% tabs %}
{% tab title="`AdbrixUnitySettings.asset`를 사용" %}
`Collect Google Advertising Id`를 체크합니다.

![AdbrixUnitySettings.asset](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-36a68e6c9b350804ab9e5f0b9f16fd1f75eb0425%2Fadbrixunitysettings.png?alt=media)
{% endtab %}

{% tab title="C# 스크립트에서 호출" %}

```csharp
Dictionary<string, object> config = new Dictionary<string, object> {
    {ABConfig.ANDROID_COLLECT_GOOGLE_ADVERTISING_ID, true} 
};
Adbrix.InitWithConfig("{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config);
```

{% endtab %}
{% endtabs %}

### App Tracking Transparency (ATT) 지원

idfa 수집 가능 시점부터 SDK 이벤트를 수집하고 싶다면 다음 설정을 추가해주세요.

{% hint style="warning" %}
해당 설정 적용 시, 적용한 시간(초) 만큼, ATTAuthorized 메소드가 호출되기 전까지 SDK 이벤트 수집이 지연됩니다.
{% endhint %}

{% tabs %}
{% tab title="`AdbrixUnitySettings.asset`를 사용" %}
`Tracking Authorize Tiemout` 을 설정합니다.

![AdbrixUnitySettings.asset](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-36a68e6c9b350804ab9e5f0b9f16fd1f75eb0425%2Fadbrixunitysettings.png?alt=media)
{% endtab %}

{% tab title="C# 스크립트에서 호출" %}

```csharp
Dictionary<string, object> config = new Dictionary<string, object> {
    {"trackingAuthorizeTimeOut", 60} 
};
Adbrix.InitWithConfig("{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config);
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
`Adbrix.ATTAuthorized(bool isAuthorized)` 메소드가 추적 허용 여부가 판단되는 시점에 호출되어야 합니다.
{% endhint %}

### App Tracking Transparency (ATT) 구현 예시

Unity의 [iOS 14 support package](https://docs.unity.com/grow/en-us/ads/ios-sdk/ios14/install-ios14-package)를 사용한 ATT 구현 예시입니다.

```csharp
using Unity.Advertisement.IosSupport;

#if UNITY_IOS && UNITY_IPHONE    
    ATTrackingStatusBinding.RequestAuthorizationTracking(OnTrackingAuthorizationCompleted);
#else
    Debug.Log("ATT는 iOS에서만 지원됩니다.");
#endif

void OnTrackingAuthorizationCompleted(int status)
{
    var authStatus = (ATTrackingStatusBinding.AuthorizationTrackingStatus)status;
    switch (authStatus)
    {
        case ATTrackingStatusBinding.AuthorizationTrackingStatus.AUTHORIZED:
            Adbrix.ATTAuthorized(true);
            break;
        case ATTrackingStatusBinding.AuthorizationTrackingStatus.NOT_DETERMINED:
            Adbrix.ATTAuthorized(false);
            break;
        case ATTrackingStatusBinding.AuthorizationTrackingStatus.DENIED:
            Adbrix.ATTAuthorized(false);
            break;
        case ATTrackingStatusBinding.AuthorizationTrackingStatus.RESTRICTED:
            Adbrix.ATTAuthorized(false);
            break;
    }
}
```

## 완료

SDK 설치 및 초기화가 완료되었습니다.