React SDK Guide
이 기능은 현재 사전 협의된 매체에만 제공됩니다.
지속적으로 개발되고 있는 기능으로, API가 예고 없이 변경될 수 있습니다.
Initial Setup
Installing React SDK
React SDK는 사내 Registry에서 NPM 패키지로 제공됩니다.
- pnpm
- npm
- Yarn
pnpm add @gfpsdk/display-sdk-react@react
npm add @gfpsdk/display-sdk-react@react
yarn add @gfpsdk/display-sdk-react@react
정식 출시 이전까지 React SDK는 사내 NPM Registry에서 latest 태그가 아닌 react 태그로 제공됩니다.
최신 빌드 버전은 여기에서 확인할 수 있습니다.
Loading Core SDK
React SDK를 사용하기 위해서는 GFP Web SDK를 먼저 로드해야합니다. 시작하기를 참고해 GFP Web SDK를 로드하는 스크립트를 추가합니다.
React SDK를 사용할 때에는 전용 Hook이 제공되므로 별도로 명령어 대기열을 생성할 필요가 없습니다.
Providing React SDK
애플리케이션의 최상위 컴포넌트에서 GladSdkProvider 컴포넌트로 애플리케이션을 감싸 React SDK를 사용할 준비를 합니다.
import { preinit } from 'react-dom';
import { GladSdkProvider } from '@gfpsdk/display-sdk-react';
export default function App() {
preinit('https://ssl.pstatic.net/tveta/libs/glad/prod/gfp-core.js', { as: 'script' });
return (
<GladSdkProvider>
<YourApp />
</GladSdkProvider>
);
}
Displaying Ad
AdSlotElement 컴포넌트를 렌더링하면 adSlotElementId를 id로 가지는 div와 AdSlot이 생성되며,
자동으로 광고 요청이 발생하고 광고가 로드됩니다.
import { AdSlotElement } from '@gfpsdk/display-sdk-react';
const adRequestOptions = {
adUnitId: 'ad-unit-id',
adSlotElementId: 'ad-slot-element-id',
};
function Sample() {
return (
<AdSlotElement adSlotOptions={adRequestOptions} />
);
}
Accessing Ad Slot
AdSlotElement 컴포넌트를 렌더링하면 adSlotElementId를 id로 가지는 div와 AdSlot이 생성됩니다.
AdSlot 인스턴스에 접근하기 위해서는, AdSlot이 생성될 때 호출되는 onAdSlotCreated 리스너를 생성해 AdSlotElement의 props로 전달하면 됩니다.
onAdSlotCreated는 AdSlot이 생성된 이후, 슬롯에 대한 광고가 요청되기 이전에 호출되므로,
이벤트 리스너를 등록하거나 광고 요청을 위한 세부 설정을 적용하는 등의 동작을 추가할 수 있습니다.
import { AdSlotElement } from '@gfpsdk/display-sdk-react';
const adRequestOptions = {
adUnitId: 'ad-unit-id',
adSlotElementId: 'ad-slot-element-id',
};
function Sample() {
const onAdSlotCreated = (adSlot) => {
adSlot.setForceSafeFrame(true);
}
return (
<AdSlotElement adSlotOptions={adRequestOptions} onAdSlotCreated={onAdSlotCreated} />
);
}
Manually displaying Ad
AdSlotElement 컴포넌트를 렌더하면 기본적으로 광고가 즉시 요청됩니다.
세부적인 제어를 위해 이 동작을 원하지 않는 경우 displayOnMount prop을 false로 설정합니다.
이후 원하는 타이밍에 직접 gladSdk.displayAd()를 호출해 광고를 표시할 수 있습니다.
Destroying Ad Slot
AdSlotElement가 Unmount되면(React Render Tree에서 제외되면) 생성된 AdSlot도 함께 Destroy됩니다.
onAdSlotCreated 리스너를 등록해 AdSlot 인스턴스에 대한 참조를 별도의 장소에 저장해두는 경우, destroy된 AdSlot에 접근하지 않도록 주의해야합니다.
또한 AdSlotElement에서 AdSlot의 LifeCycle을 관리하므로 gladSdk.destroyAdSlots()를 이용해 AdSlot을 직접 destroy하는 것은 권장되지 않습니다.
Restoring Ad Slot
AdSlotElement가 Unmount되면 AdSlot이 destroy되기 때문에,
Virtualized List와 같이 수시로 Mount/Unmount되는 컴포넌트 내부에 광고를 배치할 경우
광고가 지속적으로 새로 로드되어 부자연스러운 동작이 연출될 수 있습니다.
이를 방지하기 위해 AdSlotOptions.persistKey 옵션을 설정할 수 있습니다.
이 값은 동일한 adSlotElementId에 대해 Page Session동안 유지되는 광고에 대한 키를 지정합니다.
즉, 동일한 (adSlotElementId, persistKey)의 조합으로 AdSlot을 생성하면,
Page Session 내에서 동일한 조합으로 광고가 로드된 적이 있는 경우, 이전에 표시되었던 광고가 복원됩니다.
이 기능을 사용하려는 경우, 적절한 키를 할당해야합니다. 일반적인 경우, 컴포넌트가 마운트되어있는 동안 그 하위의 광고들이 복원되어야 하는 지점에서 키를 생성하는 것이 좋습니다.
아래 예시의 경우 VirtualizedList 컴포넌트의 자체적인 로직에 의해 그 하위의 children들이 수시로 mount/unmount되는 경우를 가정하면,
AdSlotElement가 다시 Mount되어도 adSlotElementId와 persistKey 값이 동일하기 때문에 최초 표시되었던 광고가 복원됩니다.
반면에, Sample 컴포넌트 전체가 새롭게 Mount된 경우 persistKey가 변경되어 새로운 광고가 호출됩니다.
import { AdSlotElement } from '@gfpsdk/display-sdk-react';
const adRequestOptions = {
adUnitId: 'ad-unit-id',
adSlotElementId: 'ad-slot-element-id',
};
function Sample() {
const [persistKey] = useState(() => crypto.randomUUID());
return (
<VirtualizedList>
<Post1 />
<Post2 />
<AdSlotElement adSlotOptions={{ ...adRequestOptions, persistKey }} />
<Post3 />
<Post4 />
</VirtualizedList>
);
}
이 기능을 잘못 사용하면 광고가 의도대로 표시되지 못하여 수익이 감소할 수 있습니다.
예를 들어 persistKey를 변경되지 않는 값으로 설정한 경우 해당 광고 슬롯은 Page Session이 종료될 때 까지
새로운 광고가 로드되지 않고 최초 표시되었던 광고가 계속 복원되게 됩니다.
Ad Deduplication (중복제어)
AdDeduplicationBoundary
AdDeduplicationBoundary를 사용해 중복제어를 적용할 컴포넌트 영역을 지정할 수 있습니다.
AdDeduplicationBoundary 하위에서 렌더링되는 광고들은 중복제어가 적용되어 로드됩니다.
dedupReqId는 기본값이 자동으로 생성되지만,
AdDeduplicationBoundary와 분리된 영역에 대해서 동일한 중복제어를 적용하는 등
세부적인 제어를 위해서 직접 dedupReqId를 설정할 수도 있습니다.
import { AdDeduplicationBoundary, AdSlotElement } from '@gfpsdk/display-sdk-react';
const adRequestOptions = {
adUnitId: 'ad-unit-id',
adSlotElementId: 'ad-slot-element-id',
};
const adRequestOptions2 = {
adUnitId: 'ad-unit-id-2',
adSlotElementId: 'ad-slot-element-id-2',
};
const dedupReqId = 'sample-dedup-area';
function Sample() {
return (
// dedupReqId is optional
<AdDeduplicationBoundary dedupReqId={dedupReqId}>
<AdSlotElement adSlotOptions={adRequestOptions} />
<AdSlotElement adSlotOptions={adRequestOptions2} />
</AdDeduplicationBoundary>
);
}
Individual Deduplication
개별 슬롯에 대해 직접 중복 제어를 적용하려는 경우, AdSlotElement의 dedupReqId prop을 설정합니다.
동일한 dedupReqId로 요청되는 광고들은 중복제어가 적용되어 로드됩니다.
dedupReqId가 동일하다면, 중복제어가 같이 적용됩니다.
예를 들어 서로 다른 영역에서 렌더링되는 AdDeduplicationBoundary 내부의 광고들과
AdSlotElement들에 대해서 동일한 dedupReqId를 설정하면 각 슬롯에는 서로 다른 광고 소재들이 표시됩니다.
Accessing Glad SDK Instance
React SDK는 GFP Web SDK 인스턴스에 접근할 수 있는 useGladSdk Hook을 제공합니다.
SDK 인스턴스가 초기화되기 전까지는 undefined을 반환하므로, SDK 인스턴스가 유효한지 확인한 후에 SDK 메소드를 호출해야 합니다.
import { useEffect } from 'react';
import { useGladSdk } from '@gfpsdk/display-sdk-react';
const MyComponent = () => {
const gladSdk = useGladSdk();
useEffect(() => {
if (!gladSdk) return;
gladSdk.setGlobalConfig({
gender: 'M',
});
}, [gladSdk]);
// ...
}
Accessing Glad SDK Instance without null-checking
useSuspenseGladSdk Hook을 사용하면 React 18부터 도입된 Suspense를 사용해
SDK가 초기화 될 때까지 렌더링을 지연시키고, SDK의 초기화 상태를 보장하며 Type-Safe하게 SDK 메소드에 접근할 수 있습니다.
import { useEffect } from 'react';
import { useSuspenseGladSdk } from '@gfpsdk/display-sdk-react';
const MyComponent = () => {
const gladSdk = useSuspenseGladSdk();
useEffect(() => {
gladSdk.setGlobalConfig({
gender: 'M',
});
}, [gladSdk]);
// ...
}