외형 설정

디지털 휴먼의 외형(의상, 헤어스타일 등)을 실시간으로 변경합니다.

메서드

sendAvatarAppearanceCategorySelected(appearanceType)

외형 카테고리를 선택합니다.

public sendAvatarAppearanceCategorySelected(appearanceType: string): void

매개변수

• appearanceType (string): 외형 카테고리
  • "Hair": 헤어스타일
  • "Top": 상의
  • "Bottom": 하의
  • "Shoes": 신발
  • "Persona": 페르소나
  • "Acc": 액세서리

resetAvatarAppearanceCategorySelected()

선택된 외형 카테고리를 초기화합니다.

public resetAvatarAppearanceCategorySelected(): void

sendAppearanceOptionSelected(appearanceType, appearanceId)

선택한 카테고리의 특정 외형 옵션을 적용합니다.

public sendAppearanceOptionSelected(
  appearanceType: string,
  appearanceId: string,
): void

매개변수

• appearanceType (string): 외형 카테고리 (Hair, Top, Bottom, Shoes 등)
• appearanceId (string): 외형 아이템 ID (예: "F_Hoodie_S", "F_Hair_04")

사용법

JavaScript/TypeScript

import { KleverOneClient } from "@klever-one/web-sdk/core";

const client = new KleverOneClient({
  apiKey: "your-api-key",
  container: document.getElementById("streaming-container"),
});

await client.connect();

// 1. 카테고리 선택
client.sendAvatarAppearanceCategorySelected("Top");

// 2-1. 외형 옵션 적용 (단건)
client.sendAppearanceOptionSelected("Top", "F_Hoodie_S");

// 2-2. 외형 옵션 적용 (여러 개)
const appearanceOptions = [
  { appearanceType: "Top", appearanceId: "F_Hoodie_S" },
  { appearanceType: "Bottom", appearanceId: "F_Suitpants_S" },
  { appearanceType: "Shoes", appearanceId: "F_Oxfords_S" },
  { appearanceType: "Hair", appearanceId: "F_Hair_04" },
];

appearanceOptions.forEach((option) => {
  client.sendAppearanceOptionSelected(
    option.appearanceType,
    option.appearanceId
  );
});

// 3. 카테고리 초기화
client.resetAvatarAppearanceCategorySelected();

React Hook

"use client";

import { useRef, useEffect, useMemo, useState } from "react";
import { useKleverOneClient } from "@klever-one/web-sdk/react";

function AppearanceControl() {
  const [selectedCategory, setSelectedCategory] = useState<string>("");
  const containerRef = useRef<HTMLDivElement>(null);
  const tempContainer = useMemo(() => {
    if (typeof document !== "undefined") {
      return document.createElement("div");
    }
    return {} as HTMLDivElement;
  }, []);

  const client = useKleverOneClient({
    apiKey: "your-api-key",
    container: containerRef.current || tempContainer,
    callbacks: {
      onReady: () => console.log("디지털 휴먼 준비 완료!"),
    },
  });

  useEffect(() => {
    return () => {
      if (client.client) {
        client.disconnect();
      }
    };
  }, [client.client]);

  const handleConnect = async () => {
    if (containerRef.current && client.client) {
      try {
        await client.connect();
      } catch (error) {
        console.error("연결 실패:", error);
      }
    }
  };

  const handleCategorySelect = (category: string) => {
    if (client.client) {
      setSelectedCategory(category);
      client.sendAvatarAppearanceCategorySelected(category);
    }
  };

  const handleCategoryReset = () => {
    if (client.client) {
      setSelectedCategory("");
      client.resetAvatarAppearanceCategorySelected();
    }
  };

  const handleApplySingleAppearance = () => {
    if (client.client) {
      // 단건 적용
      client.sendAppearanceOptionSelected("Top", "F_Hoodie_S");
    }
  };

  const handleApplyMultipleAppearance = () => {
    if (client.client) {
      // 여러 개 적용
      const options = [
        { appearanceType: "Top", appearanceId: "F_Hoodie_S" },
        { appearanceType: "Bottom", appearanceId: "F_Suitpants_S" },
        { appearanceType: "Shoes", appearanceId: "F_Oxfords_S" },
        { appearanceType: "Hair", appearanceId: "F_Hair_04" },
      ];

      options.forEach((option) => {
        client.sendAppearanceOptionSelected(
          option.appearanceType,
          option.appearanceId
        );
      });
    }
  };

  return (
    <div>
      <div
        ref={containerRef}
        className="h-[400px] w-[800px] bg-black rounded-lg"
      ></div>

      <div className="controls">
        <button onClick={handleConnect}>연결</button>

        <select
          value={selectedCategory}
          onChange={(e) => handleCategorySelect(e.target.value)}
          disabled={client.state.connection !== "connected"}
        >
          <option value="">카테고리 선택...</option>
          <option value="Hair">Hair</option>
          <option value="Top">Top</option>
          <option value="Bottom">Bottom</option>
          <option value="Shoes">Shoes</option>
          <option value="Persona">Persona</option>
          <option value="Acc">Acc</option>
        </select>

        <button
          onClick={handleCategoryReset}
          disabled={client.state.connection !== "connected"}
        >
          카테고리 초기화
        </button>

        <button
          onClick={handleApplySingleAppearance}
          disabled={client.state.connection !== "connected"}
        >
          외형 적용 (단건)
        </button>

        <button
          onClick={handleApplyMultipleAppearance}
          disabled={client.state.connection !== "connected"}
        >
          외형 적용 (여러 개)
        </button>
      </div>
    </div>
  );
}

외형 적용 워크플로우

1. sendAvatarAppearanceCategorySelected() - 카테고리 선택
2. sendAppearanceOptionSelected() - 외형 옵션 적용
   • 단건: 한 번 호출로 하나의 외형 적용
   • 여러 개: 여러 번 호출하여 다중 외형 적용
3. resetAvatarAppearanceCategorySelected() - 카테고리 초기화 (선택사항)

주의사항

• sendAppearanceOptionSelected()는 단건으로 호출하거나 여러 번 호출하여 다중 외형을 적용할 수 있습니다.
• 각 카테고리마다 사용 가능한 외형 ID가 다릅니다.
• 외형 변경은 연결 상태에서만 가능합니다.

관련 기능

외형 설정과 함께 사용할 수 있는 기능들:

• 액션 실행 - 제스처 및 행동 실행
• 회전 제어 - 좌우 회전으로 외형 확인
• 연결 - 디지털 휴먼 연결