> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTML로 인앱 메시지 디자인하기

> 최대한의 유연성, 반응성 및 브랜딩을 위해 OneSignal의 HTML 에디터를 사용하여 인앱 메시지를 디자인하고 사용자 지정하세요.

## 개요

OneSignal은 두 가지 인앱 메시지 에디터를 제공합니다:

* 비기술자를 위한 [드래그 앤 드롭](./design-your-in-app-message) GUI
* 레이아웃, 동작 및 반응성에 대한 픽셀 단위의 완벽한 제어를 원하는 개발자를 위한 HTML 에디터.

<Frame caption="렌더링된 인앱 옆에 인앱 코드를 보여주는 이미지">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/f33b4e3-iam-html-2.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=0a0527678d2d094109186fea726918be" width="1700" height="1000" data-path="images/docs/f33b4e3-iam-html-2.png" />
</Frame>

**HTML 에디터로 할 수 있는 것:**

* **레이아웃:** 복잡한 반응형 레이아웃 구축(예: 나란히 배치된 CTA).
* **폼:** 인라인으로 입력 수집(이메일, 피드백, 설문조사).
* **글꼴 및 브랜드:** 사용자 지정 웹 글꼴 및 CSS 변수 사용.
* **JS 액션:** 클릭 추적, 사용자 태그 지정, 결과 전송 등.

### 요구 사항

* **iOS:** 3.9.0+
* **Android:** 4.6.3+
  * 앱이 이전 SDK를 사용하는 경우 인앱 메시지는 Center Modal 레이아웃으로 렌더링됩니다.

***

## HTML 인앱 만들기 및 미리보기

**Messages > New In-App**으로 이동하여 인앱 메시지를 만들고, 편집하고, 테스트하고, 일시 중지하고, 복제하거나 삭제하세요.

<Columns cols={2}>
  <Card title="HTML Templates" href="./in-app-html-templates" arrow={true}>
    미리 만들어진 템플릿으로 빠르게 시작하세요.
  </Card>

  <Card title="In-app JavaScript Library" href="./in-app-message-api" arrow={true}>
    JavaScript 라이브러리를 사용하여 상호 작용을 추적하고 인앱 동작을 트리거하세요.
  </Card>
</Columns>

왼쪽에 HTML 코드를 입력하고 실시간으로 미리 봅니다. **Send Test In-App**을 사용하여 반응성과 디자인을 테스트하세요.

<Frame caption="미리보기 옆에 HTML 에디터를 보여주는 이미지">
  <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/04df3a9-Screenshot_2023-04-15_at_11.54.11_AM.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=db3ac070e794e0c594850a61b2f95927" width="1770" height="1198" data-path="images/docs/04df3a9-Screenshot_2023-04-15_at_11.54.11_AM.png" />
</Frame>

### 추적 가능한 레이블 추가

클릭이 추적되고 실행 가능하도록 대화형 요소에 `data-onesignal-unique-label`을 추가하세요.

```html theme={null}
<button class="tag-user" data-onesignal-unique-label="my-tag-user-button">사용자 태그 지정</button>
```

### JavaScript로 클릭 액션 바인딩

```js theme={null}
// 사용자가 버튼을 클릭할 때 사용자를 태그 지정
document.querySelector(".tag-user").onclick = (e) => {
  OneSignalIamApi.tagUser(e, { fiz: "baz" });
};
```

<Note>
  자세한 내용은 [In-App JS 라이브러리 문서](./in-app-message-api)를 참조하세요.
</Note>

### 에셋 지원

에셋은 제공한 URL에서 렌더링 시간에 로드됩니다.

```html theme={null}
<img src="https://media.onesignal.com/iam/default_image_20200320.png" alt="프로모" />
```

### 개인화

[Liquid 구문 사용](./using-liquid-syntax)을 사용하여 사용자 데이터 값을 동적으로 삽입하세요:

```html theme={null}
<div>안녕하세요 {{ name | default: '회원님' }}!</div>
```

**지원되는 컨텍스트:**

* `div`, `p`, `li`와 같은 요소 내부의 텍스트
* `<style>` 블록 내부
* `href`, `src`, `action` 및 `data` 속성에서

**지원되지 않는 곳:**

* `<script>` 태그 내부
* 구문 분석이 모호해지는 복잡하게 중첩된 콘텐츠 전체, 예:

```html theme={null}
<div>
  안녕하세요 {{name}}
  <span>쿠폰을 받으세요!</span>
</div>
```

***

## 접근성 및 반응형 디자인

CSS 미디어 쿼리와 플랫폼 타이포그래피를 사용하여 기기 크기와 OS 텍스트 설정에 적응하세요.

```css theme={null}
@media only screen and (max-width: 620px) {
  .btn-primary { width: 100% !important; }
}
/* iOS에서 동적 텍스트 크기 존중 */
:root { font: -apple-system-body; }
```

### 안전 영역(노치, 홈 바)

최신 기기에는 안전 영역(노치 또는 홈 바 같은)이 있습니다. `safe-area-inset-*` 변수를 사용하여 레이아웃에 패딩을 추가하세요:

```css theme={null}
body {
  padding-top: var(--safe-area-inset-top);
  padding-right: var(--safe-area-inset-right);
  padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
  padding-left: var(--safe-area-inset-left);
  margin: 0;
}
```

### 비디오 삽입

`<iframe>`을 사용하여 인앱 메시지에 비디오(예: YouTube, Vimeo)를 직접 삽입할 수 있습니다.
이는 데모, 프로모 또는 온보딩 플로우에 유용합니다.

대부분의 브라우저는 **비디오가 음소거 상태로 시작하는 경우에만 자동 재생을 허용**하므로 삽입 URL에 항상 `&mute=1`을 포함하세요.

<Note>
  자동 재생 비디오는 성능에 영향을 미칠 수 있습니다. 비디오를 짧게 유지하고 단일 인앱에서 여러 자동 재생 삽입을 피하세요.
</Note>

#### 예제: 자동 재생 YouTube 삽입

아래 스니펫은 고정 크기(560×315)로 인앱 중앙에 YouTube 비디오를 중앙에 배치하는 방법을 보여줍니다:

```html theme={null}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <style>
      body {
        margin: 0;
        height: 100vh;
        display: flex;
        justify-content: center; /* 가로 중앙 정렬 */
        align-items: center;     /* 세로 중앙 정렬 */
        background: #f0f0f0;     /* 선택적 배경 */
      }
      .video-box {
        width: 560px;  /* 고정 너비 */
        height: 315px; /* 고정 높이 (16:9 비율) */
        box-shadow: 0 4px 12px rgba(0,0,0,0.2);
        border-radius: 8px;
        overflow: hidden;
        background: #000;
      }
      .video-box iframe {
        width: 100%;
        height: 100%;
        border: none;
      }
    </style>
  </head>
  <body>
    <div class="video-box">
      <iframe src="https://www.youtube.com/embed/bH60T1PZg1c?autoplay=1&mute=1"
        allow="autoplay; encrypted-media"
        allowfullscreen>
      </iframe>
    </div>
  </body>
</html>
```

#### 자동 재생 동작 이해

* 자동 재생에는 삽입 URL(/embed/VIDEO\_ID)이 필요합니다 — 일반 watch?v= 링크는 작동하지 않습니다.

* ?autoplay=1\&mute=1을 추가하면 비디오가 자동으로 재생되고 브라우저 자동 재생 규칙을 준수합니다.

* allow="autoplay; encrypted-media" 속성은 자동 재생에 대한 권한을 부여합니다.

* .video-box는 고정 560×315px 크기(YouTube의 기본 16:9)를 사용하므로 비디오가 전체 화면으로 늘어나는 대신 포함된 것으로 나타납니다.

* body는 justify-content: center 및 align-items: center가 있는 flex 컨테이너로 설정되어 비디오 박스를 화면 정중앙에 배치합니다.

***

## 성능 팁

* 중요한 CSS를 인라인으로 사용하고 무거운 스크립트는 지연시키세요.
* 이미지 최적화(`object-fit`이 있는 크기가 지정된 `<img>`), 가능하면 최신 형식을 사용하세요.
* HTML 페이로드를 간결하게 유지하고 큰 base64 blob을 피하세요.
* 시스템 글꼴을 사용하거나 `font-display: swap`으로 성능이 좋은 웹 글꼴을 호스팅하세요.
* 파일 크기를 줄이고 적절한 해상도를 사용하세요:
  * [Apple 이미지 가이드라인](https://developer.apple.com/design/human-interface-guidelines/ios/icons-and-images/image-size-and-resolution/)
  * [Android 이미지 개요](https://developer.android.com/guide/topics/graphics)
  * OneSignal은 [imagekit.io](https://imagekit.io/)와 제휴 관계가 없지만 최적화에 유용한 도구입니다.

### 기기 전체에서 테스트

기기 유형 전체에서 동작과 레이아웃을 확인하기 위해 테스트 메시지를 자주 보내세요. [테스트 구독 찾기 및 설정](./test-users)을 참조하세요.

***

## FAQ

### 배너 스타일 인앱에서 회색 배경 또는 그림자를 제거할 수 있나요?

예. 상단/하단 배너의 경우 SDK를 업데이트하고 다음을 설정하세요:

**iOS 5.1.5+**

```xml theme={null}
<key>OneSignal_in_app_message_hide_drop_shadow</key>
<true/>
<key>OneSignal_in_app_message_hide_gray_overlay</key>
<true/>
```

**Android 5.1.9+**

```xml theme={null}
<meta-data android:name="com.onesignal.inAppMessageHideGrayOverlay" android:value="true"/>
<meta-data android:name="com.onesignal.inAppMessageHideDropShadow" android:value="true"/>
```

### 다른 공급자의 인앱 템플릿을 재사용할 수 있나요?

예. HTML을 에디터에 붙여넣고 분석/액션을 OneSignal In‑App JS 메서드로 바꾸세요.

### 템플릿이 없습니다. 어떻게 시작하나요?

제공된 스타터 템플릿을 사용하거나 [사용 가능한 템플릿을 탐색](./in-app-html-templates)하세요. 일부 HTML/CSS 경험이 권장됩니다.

### 어떤 SDK 버전이 필요한가요?

* **iOS:** 3.9.0+
* **Android:** 4.6.3+

이전 SDK는 Center Modal 렌더링으로 폴백됩니다.

### 인앱 메시지가 오프라인에서 작동하나요?

아니요. 메시지는 콘텐츠를 가져오고 렌더링하기 위해 활성 인터넷 연결이 필요합니다.

***
