> For the complete documentation index, see [llms.txt](https://docs.dfinery.ai/developer-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dfinery.ai/developer-guide/platform/unity/integration.md).

# 연동하기

이 문서는 DFINERY Unity SDK를 Unity에 통합하는 방법을 다룹니다. DFINERY SDK를 설치하면 이벤트 분석 기능과 유저 프로필 기능 그리고 액션 기능이 제공됩니다.

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

## 시작하기 전에

### 서비스 설정

[DFINERY 콘솔](https://console.dfinery.ai/)의 서비스 관리/서비스 정보 페이지에서 데이터 소스 항목에 사용하시려는 플랫폼을 체크하셔야 합니다.

![서비스 정보](/files/kByxg9Ww4QXDmsd2ecNT)

### 지원 정보

#### Android

* 최소 지원 SDK : Android 4.4+ / API 19+
* 컴파일 SDK : 34

#### iOS

* iOS 12.0
* Xcode 16.0

### 의존성

#### Android

* [androidx.core:core:1.5.0](https://mvnrepository.com/artifact/androidx.core/core)
* [com.google.android.gms:play-services-appset:16.0.2](https://mvnrepository.com/artifact/com.google.android.gms/play-services-appset)
* [com.google.android.gms:play-services-ads-identifier:18.0.0](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 클릭하기](/files/BnPSGpfxyhVnTEjlKXRf)

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

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

![Install package from git url 클릭하기](/files/qtLx8uKbTeKFriYDHhya)

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

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

![URL 입력](/files/933UTN5LsGeKaFAuqMMj)

**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 사용" %}
**DFINERY Unity Package를 사용하여 SDK 추가하기**

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

**1.** [**Release의 Assets**](https://github.com/IGAWorksDev/dfinery-unity-sdk/releases)**에서 DFINERY 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/dfinery-unity-sdk/releases/) **페이지의 Assets에서 사용하려는 버전의 DFINERY SDK Android Archive package(.aar) 파일, iOS xcframework를 다운로드 합니다.**

```
dfinery-android-sdk-[SDK-VERSION].aar
dfinery-unity-extension-[EXTENSION-VERSION].aar
DfinerySDK.xcframework.zip
```

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

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

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

* [androidx.core:core](https://mvnrepository.com/artifact/androidx.core/core)
* [com.google.android.gms:play-services-appset](https://mvnrepository.com/artifact/com.google.android.gms/play-services-appset)
* [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` 에 `DfinerySDK.xcframework` 를 추가합니다.

`Targets / UnityFramework / General / Frameworks and Libraries` 에 `DfinerySDK.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 %}

DFINERY를 사용하기 위해서는 `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.dfinery.unity.DfineryUnityInitProvider`를 추가해주세요.**

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

```xml
<provider android:authorities="${applicationId}.dfinery.unity.INIT_PROVIDER" android:name="com.igaworks.dfinery.unity.DfineryUnityInitProvider" 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}.dfinery.unity.INIT_PROVIDER" android:name="com.igaworks.dfinery.unity.DfineryUnityInitProvider" android:exported="false" />
  </application>
</manifest>
```

{% endtab %}
{% endtabs %}

## SDK 초기화

### 초기화 하기

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

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

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

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

**2. Service ID를 입력하고 필요한 설정을 적용합니다.**

{% hint style="info" %}
Service ID는 [DFINERY Console](https://console.dfinery.ai/)의 `서비스 관리/서비스 정보/Key 정보/서비스키` 경로에서 확인이 가능합니다.
{% endhint %}

![Dfinery Unity Settings](/files/GC8lO79vm1lsZ1WPO1LO)

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

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

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

```csharp
using DfineryPlugin;
```

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

{% hint style="info" %}
Service ID는 [DFINERY Console](https://console.dfinery.ai/)의 `서비스 관리/서비스 정보/Key 정보/서비스키` 경로에서 확인이 가능합니다.
{% endhint %}

```csharp
public void Awake() {
    Dictionary<string, object> config = new Dictionary<string, object> {
        {DFConfig.IOS_LOG_ENABLE, true},
        {DFConfig.ANDROID_LOG_ENABLE, true},
        {DFConfig.ANDROID_LOG_LEVEL, DFAndroidLogLevel.VERBOSE}
    };
    Dfinery.InitWithConfig("{YOUR_SERVICE_ID}", config);
}
```

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

### 구글 광고 ID 설정하기(선택사항)

Google 광고 ID를 수집하기 위해선 `setGoogleAdvertisingId()` 메소드를 통해 수동으로 설정해야합니다.

#### 1. AndroidManifest.xml에 필요한 권한을 추가합니다.

```xml
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
```

#### 2. `setGoogleAdvertisingId()` 메소드를 통해 광고 ID를 설정합니다.

{% hint style="info" %}
`Dfinery.getGoogleAdvertisingId()`은 [Play Services Ads Identifier](https://mvnrepository.com/artifact/com.google.android.gms/play-services-ads-identifier) API를 사용하여 광고 ID를 가져옵니다. 다른 방법으로 광고 ID를 가져와 설정하셔도 무관합니다.
{% endhint %}

```csharp
public void RefreshGoogleAdvertisingId() {
    Dfinery.GetGoogleAdvertisingId((googleAdvertisingId, isLimitAdTrackingEnabled) => {
        if (!string.IsNullOrEmpty(googleAdvertisingId)) {
            Dfinery.SetGoogleAdvertisingId(googleAdvertisingId, isLimitAdTrackingEnabled);
        }
    });
}
```

## SDK 설정

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

### 로그 활성화 하기

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

![Dfinery Unity Settings](/files/GC8lO79vm1lsZ1WPO1LO)
{% endtab %}

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

```csharp
Dictionary<string, object> config = new Dictionary<string, object> {
    {DFConfig.IOS_LOG_ENABLE, true},
    {DFConfig.ANDROID_LOG_ENABLE, true},
};
Dfinery.InitWithConfig("{YOUR_SERVICE_ID}", config);
```

{% endtab %}
{% endtabs %}

### 로그 레벨 변경하기

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

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

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

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

![Dfinery Unity Settings](/files/GC8lO79vm1lsZ1WPO1LO)
{% endtab %}

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

```csharp
Dictionary<string, object> config = new Dictionary<string, object> {
    {DFConfig.ANDROID_LOG_LEVEL, DFAndroidLogLevel.VERBOSE},
};
Dfinery.InitWithConfig("{YOUR_SERVICE_ID}", config);
```

{% endtab %}
{% endtabs %}

## 완료

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.dfinery.ai/developer-guide/platform/unity/integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.