> ## 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.

# iOS 웹 푸시 설정

> Safari, Chrome 및 Edge 브라우저에 대한 manifest 파일 설정, 사용자 온보딩 전략 및 구현 모범 사례를 포함하여 iOS 및 iPadOS 기기에서 웹 푸시 알림을 활성화하는 완벽한 가이드입니다.

export const SdkReleasesIframe = ({sdkFilter = undefined, viewMode = undefined, height, ...frameProps}) => {
  const baseUrl = 'https://onesignal.github.io/sdk-releases';
  const buildUrl = (theme, sdkFilter, viewMode) => {
    const url = new URL(baseUrl);
    const params = new URLSearchParams();
    if (theme) {
      params.set('theme', theme);
    }
    if (sdkFilter) {
      params.set('sdk', sdkFilter);
    }
    if (viewMode) {
      params.set('viewMode', viewMode);
    }
    if (params.toString()) {
      url.search = params.toString();
    }
    return url.toString();
  };
  const detectTheme = () => {
    if (document.documentElement.classList.contains('dark')) {
      return 'dark';
    }
    return 'light';
  };
  const [theme, setTheme] = useState('light');
  const [iframeSrc, setIframeSrc] = useState(() => {
    const initialTheme = detectTheme();
    return buildUrl(initialTheme, sdkFilter, viewMode);
  });
  useEffect(() => {
    const currentTheme = detectTheme();
    setTheme(currentTheme);
    setIframeSrc(buildUrl(currentTheme, sdkFilter, viewMode));
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    const handleThemeChange = () => {
      const newTheme = detectTheme();
      setTheme(newTheme);
      setIframeSrc(buildUrl(newTheme, sdkFilter, viewMode));
    };
    if (mediaQuery.addEventListener) {
      mediaQuery.addEventListener('change', handleThemeChange);
    } else {
      mediaQuery.addListener(handleThemeChange);
    }
    window.addEventListener('storage', handleThemeChange);
    const observer = new MutationObserver(handleThemeChange);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ['class', 'data-theme']
    });
    return () => {
      if (mediaQuery.removeEventListener) {
        mediaQuery.removeEventListener('change', handleThemeChange);
      } else {
        mediaQuery.removeListener(handleThemeChange);
      }
      window.removeEventListener('storage', handleThemeChange);
      observer.disconnect();
    };
  }, [sdkFilter, viewMode]);
  const getIframeHeight = () => {
    if (viewMode === 'table') {
      return '450';
    }
    if (viewMode === 'mini') {
      return '170';
    }
    return '800';
  };
  const iframeHeight = height || getIframeHeight();
  return <Frame {...frameProps}>
      <iframe src={iframeSrc} width="100%" height={iframeHeight} frameBorder="0" style={{
    border: "none"
  }} title="SDK Releases" key={iframeSrc} />
    </Frame>;
};

<SdkReleasesIframe sdkFilter="react,vue,vue3,angular,wordpress" viewMode="table" height="380" />

Apple은 사용자의 홈 화면에 추가된 웹 앱에 대해 iOS 및 iPadOS 16.4+에서 푸시 알림 지원을 시작했습니다. 이 기능은 Safari, Chrome 및 Edge 브라우저에서 작동하며 웹 우선 회사에 새로운 참여 기회를 제공합니다. 이 종합 가이드에서는 iOS 웹 푸시 알림을 성공적으로 구현하는 데 필요한 모든 것을 다룹니다.

<Frame caption="모바일에서의 웹 푸시 알림 예시입니다.">
  <img src="https://mintcdn.com/onesignal/3zq1PvSaqvUE2bIx/images/docs/2477862-iOS_push-doc.jpg?fit=max&auto=format&n=3zq1PvSaqvUE2bIx&q=85&s=86aed6cdbed6645e568a644ac725f414" width="806" height="929" data-path="images/docs/2477862-iOS_push-doc.jpg" />
</Frame>

***

## 2025년 중요 업데이트

**크로스 브라우저 지원**: 웹 푸시 알림은 이제 Safari, Chrome 및 Edge를 포함한 iOS/iPadOS 16.4+의 모든 주요 브라우저에서 작동합니다.

**iOS 17+ 개선 사항**: 기본적으로 활성화된 관련 API로 향상된 구현으로 사용자가 웹 푸시에 더 쉽게 액세스할 수 있습니다.

**안정성 고려 사항**: 일부 개발자는 iOS 웹 푸시 알림이 처음에는 작동하다가 예기치 않게 중지될 수 있는 간헐적인 안정성 문제를 보고합니다. 알림 전달률을 모니터링하고 대체 참여 전략을 마련하세요.

***

## 요구 사항

* **iOS/iPadOS 버전**: 16.4 이상
* **HTTPS Origin**: 반응형 디자인이 있는 보안 연결
* **웹 애플리케이션 Manifest**: 올바른 설정이 있는 유효한 `manifest.json` 파일
* **홈 화면 설치**: 지원되는 모든 브라우저에서 웹 앱을 사용자의 홈 화면에 추가해야 함
* **사용자 시작 작업**: 권한 프롬프트가 나타나기 전에 사용자가 사이트와 상호작용해야 함
* **OneSignal Service Worker**: 알림 전달에 필요

### Progressive Web App(PWA) 확인

웹사이트가 이미 [Progressive Web App(PWA)](https://onesignal.com/blog/what-is-a-pwa/)인 경우 추가 사이트 업데이트가 필요하지 않습니다. [Chrome DevTools의 Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/#devtools)를 사용하여 사이트가 PWA 자격을 갖추었는지 감사하세요.

***

## 설정

### 1. 웹 애플리케이션 Manifest 생성

웹 애플리케이션 Manifest(`manifest.json`)는 사용자 기기에 설치될 때 웹 애플리케이션이 표시되고 작동하는 방식을 정의하는 JSON 파일입니다. iOS 웹 푸시의 경우 이 파일은 **필수**입니다.

#### 필수 Manifest 필드

`manifest.json`에는 다음 필수 필드가 포함되어야 합니다:

* **`$schema`** (권장): 검증 및 IDE 지원을 위한 JSON 스키마 URL
* **`name`** (필수): 사용자에게 표시되는 전체 애플리케이션 이름
* **`display`** (필수): iOS 호환성을 위해 `"standalone"` 또는 `"fullscreen"`으로 설정해야 함
* **`start_url`** (필수): 애플리케이션이 시작될 때의 진입점 URL
* **`icons`** (필수): 여러 크기의 아이콘 객체 배열
* **`id`** (권장): 여러 앱 인스턴스를 허용하는 고유 식별자

#### Manifest 파일 예시

```json theme={null}
{
  "$schema": "https://json.schemastore.org/web-manifest-combined.json",
  "name": "OneSignal Manifest Example",
  "short_name": "OS Manifest",
  "display": "standalone",
  "start_url": "/",
  "theme_color": "#E54B4D",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icon-192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-256x256.png", "sizes": "256x256", "type": "image/png" },
    { "src": "/icon-384x384.png", "sizes": "384x384", "type": "image/png" },
    { "src": "/icon-512x512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "id": "?homescreen=1"
}
```

#### 구현 단계

1. **파일 배치**: `manifest.json`을 웹사이트의 루트 디렉토리에 배치하세요
2. **HTML 통합**: 모든 페이지의 `<head>` 섹션에 이 링크 태그를 추가하세요:

```html theme={null}
<link rel="manifest" href="/manifest.json"/>
```

3. **아이콘 준비**: 여러 크기(192x192, 256x256, 384x384, 512x512 픽셀 권장)로 고품질 PNG 아이콘을 생성하세요

<Note>
  [SimiCart Manifest Generator](https://www.simicart.com/manifest-generator.html/)와 같은 도구를 사용하여 Manifest 파일을 빠르게 생성하거나 [Manifest Tester](https://manifesttester.com/)로 기존 파일을 검증하세요.
</Note>

### 2. OneSignal Service Worker 추가

[웹 SDK 설정](./web-sdk-setup)을 이미 완료했고 다른 브라우저에서 웹 푸시 알림을 받을 수 있다면 이 단계는 완료된 것입니다. 자세한 설정 지침은 [OneSignal Service Worker](./onesignal-service-worker) 문서를 참조하세요.

### 3. 권한 프롬프트 구성

[웹 SDK 설정](./web-sdk-setup)의 기존 [웹 권한 프롬프트](./permission-requests)는 **사용자가 사이트를 홈 화면에 추가하고 거기에서 연 후에만** iOS 기기에서 작동합니다. 이것은 Apple의 디자인 요구 사항입니다.

### 4. 사용자에게 "홈 화면에 추가" 안내

설정에 따라 권한 프롬프트가 나타나는 데스크톱 또는 Android 기기와 달리 iOS는 사용자가 완료해야 하는 특정 사용자 여정이 필요합니다.

#### 필수 사용자 여정

사용자가 알림을 받으려면 다음 단계를 완료해야 합니다:

1. iOS/iPadOS 16.4+의 Safari, Chrome 또는 Edge에서 웹사이트 방문
2. 브라우저의 **공유** 버튼 클릭
3. **홈 화면에 추가** 옵션 선택
4. 기기에 앱 저장
5. 홈 화면에서 앱 열기(브라우저가 아님)
6. 구독 버튼과 상호작용하여 기본 권한 프롬프트 트리거

<Frame caption="iOS에서 홈 화면에 웹사이트 추가">
  <img src="https://mintcdn.com/onesignal/2iWYYuHf1gqm06bv/images/docs/638b3a1-ios-web-push-add-to-home-screen.jpg?fit=max&auto=format&n=2iWYYuHf1gqm06bv&q=85&s=54cb44f40d70397099b32375a3e97683" width="1346" height="736" data-path="images/docs/638b3a1-ios-web-push-add-to-home-screen.jpg" />
</Frame>

#### 사용자 온보딩 전략

이 프로세스는 직관적이지 않으므로 다음을 통해 명확한 안내를 구현하세요:

* **웹사이트 배너**: 모바일 Apple 기기에서 특별히 알림의 가치를 설명하고 단계별 지침을 제공하는 배너를 표시하세요.

* **시각적 가이드**: 스크린샷과 화살표를 사용하여 사용자에게 정확히 어디를 탭해야 하는지 보여주세요.

* **타이밍**: 사용자가 콘텐츠에 대한 참여를 보여준 후 안내를 제시하세요.

#### 구현 예시

다음은 실제 애플리케이션의 효과적인 접근 방식입니다:

<Frame caption="사용자에게 홈 화면에 추가하도록 유도하는 배너 예시">
  <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/0b97752-image.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=bfec43a31639c25a6eab85961334a8bd" width="2055" height="1257" data-path="images/docs/0b97752-image.png" />
</Frame>

<Frame caption="단계별 시각적 안내">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4e970c1-image.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=04aef274f934dd44f34eaa8bd7e37360" width="2055" height="1257" data-path="images/docs/4e970c1-image.png" />
</Frame>

<Frame caption="혜택 중심 메시징">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/208b123-image.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=c8bd38cfb229c68500a9260b8b6e4b33" width="2055" height="1257" data-path="images/docs/208b123-image.png" />
</Frame>

<Frame caption="시각적 단서가 있는 명확한 행동 유도">
  <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7ec125a-image.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=c532cb02bcde365092a6bc001beaaf06" width="2055" height="1257" data-path="images/docs/7ec125a-image.png" />
</Frame>

#### 오픈 소스 솔루션

다음 인기 있는 오픈 소스 배너 솔루션 구현을 고려하세요:

**GitHub 프로젝트**: [rajatsehgal의 add-to-home-screen](https://github.com/rajatsehgal/add-to-home-screen)

<Frame caption="rajatsehgal의 오픈 소스 프로젝트에서 가져온 홈 화면에 추가 배너 프롬프트의 예시입니다.">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b63b31f-GitHub_A2HS_Ex_1.jpg?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=ccc678721ffc636fa5ddb4a71efb7ed0" width="1149" height="2142" data-path="images/docs/b63b31f-GitHub_A2HS_Ex_1.jpg" />
</Frame>

추가 배너 예시 및 모범 사례는 [web.dev](https://web.dev/promote-install/)에서 확인할 수 있습니다.

### 5. 테스트 및 검증

#### Manifest 파일 테스트

1. **액세스 가능성 확인**: `https://yoursite.com/manifest.json`으로 이동하여 공개 액세스 가능성을 확인하세요
2. **브라우저 DevTools**:
   * Chrome DevTools 열기(F12)
   * Application 탭 → Manifest로 이동
   * 오류 또는 경고 검토
3. **온라인 검증 도구**:
   * [Manifest Tester](https://manifesttester.com/)
   * [Redirection.io Validator](https://redirection.io/tools/web-app-manifest/validator)
   * [ValidBot Manifest Wizard](https://www.validbot.com/tools/app-manifest-wizard.php)

#### 엔드투엔드 푸시 알림 테스트

1. Safari, Chrome 또는 Edge를 사용하여 iOS 16.4+ 기기에서 웹사이트 방문
2. 브라우저의 **공유** 버튼 클릭
3. **홈 화면에 추가** 선택
4. 기기에 앱 저장
5. 홈 화면에서 앱 열기(중요한 단계)
6. 구독 버튼 트리거 - 기본 권한 프롬프트가 나타나야 함
7. 권한 부여 및 알림 전달 테스트

#### 중요한 테스트 참고 사항

**재테스트 요구 사항**: 동일한 기기에서 다시 테스트하려면:

* 홈 화면에서 앱 제거
* 브라우저 캐시 지우기(설정 > Safari/Chrome/Edge > 캐시 지우기)
* 프로세스 반복

**권한 거부 복구**: 권한이 거부된 경우 권한 프롬프트가 다시 나타나려면 홈 화면 앱을 제거하고 다시 추가해야 합니다.

**확인해야 할 일반적인 문제**:

* `display` 필드가 `"standalone"` 또는 `"fullscreen"`인지 확인
* 모든 아이콘 경로가 액세스 가능한지 확인
* Manifest가 올바른 MIME 유형(`application/manifest+json`)으로 제공되는지 확인
* CORS 오류 테스트

***

## 문제 해결

**Manifest가 로드되지 않음**: 파일 경로, HTTPS 요구 사항 및 서버의 MIME 유형 구성을 확인하세요.

**아이콘이 표시되지 않음**: 아이콘 파일 액세스 가능성과 Manifest의 올바른 크기 사양을 확인하세요.

**권한 프롬프트가 나타나지 않음**: 사용자가 홈 화면 앱을 통해 사이트에 액세스했고 먼저 대화형 요소를 클릭했는지 확인하세요.

**알림이 전달되지 않음**: OneSignal Service Worker가 올바르게 설치되었는지 확인하고 브라우저 콘솔에서 오류를 확인하세요.

***

## 다음 단계

<Check>
  이제 알림을 보낼 준비가 되었습니다! [푸시](./push) 문서를 계속하거나 [메시지 생성](/reference/create-message) API를 사용하여 웹 푸시 알림으로 iOS 사용자와 소통을 시작하세요.
</Check>

지속적인 성공을 위해 iOS 웹 푸시 성능 지표를 모니터링하고 iOS 사용자에게 필요한 추가 단계를 우아하게 처리하면서 다른 플랫폼에서 원활한 경험을 제공하는 점진적 향상 전략 구현을 고려하세요.

***
