Addressables 원격 콘텐츠와 profile

Quick Flow

기준: Unity 6.5용 Addressables 2.7.6. 원격 콘텐츠는 "remote group을 만들면 끝"이 아니라 build 결과, CDN publish, catalog 확인, dependency download, cache, fallback을 한 배포 단위로 운영하는 기능입니다.

단계	필요한 설정·API	실패했을 때 정책
환경 선택	Profile의 local/remote build·load path	dev/staging/prod URL이 빌드 산출물과 맞는지 중단합니다.
build·publish	Group의 build/load path, Content Update Restriction, immutable bundle URL	catalog가 가리키는 bundle을 먼저 접근 가능하게 둡니다.
시작 시 확인	`CheckForCatalogUpdates`	네트워크 실패 시 기존 catalog로 갈지 시작을 막을지 정합니다.
catalog 적용	`UpdateCatalogs`	gameplay load와 겹치지 않는 전환 지점에서 처리합니다.
사전 다운로드	`GetDownloadSizeAsync`, `DownloadDependenciesAsync`	용량·실패·재시도·오프라인 UI를 제공합니다.

Profile과 Group Inspector

Profile은 local/remote content의 build path와 load path에 쓸 변수를 정의합니다. 개발·테스트·staging·운영은 URL이 다르므로 Profile을 나누고, content build를 실행한 Profile과 CDN에 올린 결과를 배포 기록으로 남깁니다. Profile은 경로 치환 도구이지 환경 보안 경계가 아닙니다. secret이나 권한을 Profile string에 넣지 않습니다.

Group Inspector 값	의미	바꾸는 때	잘못되면
`Build Path`	bundle을 build할 위치	local/remote 배포 경계를 정할 때	올린 파일과 catalog가 참조하는 산출물이 다릅니다.
`Load Path`	런타임이 bundle을 찾을 URL/경로	dev·staging·CDN 환경을 바꿀 때	운영 build가 개발 host를 요청합니다.
Bundle packing	asset을 어떤 bundle 묶음으로 만들지	같이 내려받고 같이 갱신될 asset을 정할 때	작은 변경이 큰 재다운로드를 만듭니다.
`Content Update Restriction`	출시 뒤 수정 가능한 group인지	앱 build 이후 update 계획을 정할 때	규칙과 다른 asset 변경이 예상 밖 bundle 이동·재배포를 만듭니다.
Remote catalog/update 설정	runtime catalog 확인 방식	앱 시작·메뉴 전환 정책을 정할 때	업데이트 타이밍과 load가 경쟁합니다.

catalog와 cache 운영

catalog는 key가 어떤 bundle/dependency를 가리키는지 알려 주는 index입니다. content update는 이전 앱 build와 그 build의 Addressables 상태를 기준으로 만들며, catalog update API로 runtime에서 확인·적용할 수 있습니다. 새 catalog를 먼저 공개하고 bundle을 나중에 올리면 새 catalog가 아직 없는 파일을 가리킬 수 있습니다. 새 bundle upload와 접근 검증을 먼저 하고, catalog를 마지막에 publish하는 순서를 사용합니다.

bundle URL은 가능한 한 version/hash가 바뀌는 immutable 경로로 publish합니다. 같은 URL의 bundle을 CDN cache 뒤에서 덮어쓰면 일부 client는 catalog는 새것인데 cache는 옛 bundle을 받는 상태가 됩니다. rollback도 Addressables가 자동으로 해결하지 않습니다. 이전 catalog와 이전 bundle set을 되돌릴 수 있는 publish 기록과 CDN 정책이 필요합니다.

csharp

using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using UnityEngine.ResourceManagement.ResourceLocations;

private async Task<bool> TryUpdateCatalogs()
{
    AsyncOperationHandle<List<string>> check = Addressables.CheckForCatalogUpdates(false);
    await check.Task;

    if (check.Status != AsyncOperationStatus.Succeeded)
    {
        Addressables.Release(check);
        return false; // 기존 catalog로 계속할지 caller 정책으로 결정
    }

    List<string> catalogIds = new(check.Result);
    Addressables.Release(check);
    if (catalogIds.Count == 0) return true;

    AsyncOperationHandle<List<IResourceLocator>> update = Addressables.UpdateCatalogs(catalogIds, false);
    await update.Task;
    bool updated = update.Status == AsyncOperationStatus.Succeeded;
    Addressables.Release(update);
    return updated;
}

catalog update와 동시에 진행 중인 asset load가 있다면 operation이 기다리거나 대기열이 생길 수 있습니다. 로그인 뒤 main menu처럼 load owner가 명확한 전환 지점에서 update를 실행하고, 실패 재시도 횟수·offline fallback·사용자 메시지를 서비스 정책으로 정합니다.

배포 전 점검

확인	이유
build Profile과 CDN 환경이 일치	path 불일치로 client가 잘못된 host를 요청하는 것을 막습니다.
새 bundle URL을 client 관점에서 요청	catalog publish 전에 접근 권한·CORS·cache header를 검증합니다.
catalog update 성공·실패·offline 경로	연결 실패가 무한 재시도나 빈 화면으로 가지 않게 합니다.
`GetDownloadSizeAsync`와 `DownloadDependenciesAsync` 테스트	preload 용량과 cache hit/miss UX를 확인합니다.
Content Update Restriction과 변경 asset 비교	update build가 의도한 bundle만 바꾸는지 확인합니다.
이전 catalog/bundle rollback 기록	새 콘텐츠 문제 때 명시적으로 되돌릴 수 있게 합니다.

원격 콘텐츠는 CDN URL을 넣는 기능이 아니라 배포 순서와 복구 책임을 코드·CI·운영자가 나눠 갖는 시스템입니다. catalog 확인 실패를 "다시 시도"로만 처리하지 말고, 기존 콘텐츠 허용 여부와 새 콘텐츠 필수 여부를 제품 정책으로 먼저 정하세요.

참고 링크

3 sources

Quick Flow

단계	필요한 설정·API	실패했을 때 정책
환경 선택	Profile의 local/remote build·load path	dev/staging/prod URL이 빌드 산출물과 맞는지 중단합니다.
build·publish	Group의 build/load path, Content Update Restriction, immutable bundle URL	catalog가 가리키는 bundle을 먼저 접근 가능하게 둡니다.
시작 시 확인	`CheckForCatalogUpdates`	네트워크 실패 시 기존 catalog로 갈지 시작을 막을지 정합니다.
catalog 적용	`UpdateCatalogs`	gameplay load와 겹치지 않는 전환 지점에서 처리합니다.
사전 다운로드	`GetDownloadSizeAsync`, `DownloadDependenciesAsync`	용량·실패·재시도·오프라인 UI를 제공합니다.

Profile과 Group Inspector

Group Inspector 값	의미	바꾸는 때	잘못되면
`Build Path`	bundle을 build할 위치	local/remote 배포 경계를 정할 때	올린 파일과 catalog가 참조하는 산출물이 다릅니다.
`Load Path`	런타임이 bundle을 찾을 URL/경로	dev·staging·CDN 환경을 바꿀 때	운영 build가 개발 host를 요청합니다.
Bundle packing	asset을 어떤 bundle 묶음으로 만들지	같이 내려받고 같이 갱신될 asset을 정할 때	작은 변경이 큰 재다운로드를 만듭니다.
`Content Update Restriction`	출시 뒤 수정 가능한 group인지	앱 build 이후 update 계획을 정할 때	규칙과 다른 asset 변경이 예상 밖 bundle 이동·재배포를 만듭니다.
Remote catalog/update 설정	runtime catalog 확인 방식	앱 시작·메뉴 전환 정책을 정할 때	업데이트 타이밍과 load가 경쟁합니다.

catalog와 cache 운영

csharp

using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using UnityEngine.ResourceManagement.ResourceLocations;

private async Task<bool> TryUpdateCatalogs()
{
    AsyncOperationHandle<List<string>> check = Addressables.CheckForCatalogUpdates(false);
    await check.Task;

    if (check.Status != AsyncOperationStatus.Succeeded)
    {
        Addressables.Release(check);
        return false; // 기존 catalog로 계속할지 caller 정책으로 결정
    }

    List<string> catalogIds = new(check.Result);
    Addressables.Release(check);
    if (catalogIds.Count == 0) return true;

    AsyncOperationHandle<List<IResourceLocator>> update = Addressables.UpdateCatalogs(catalogIds, false);
    await update.Task;
    bool updated = update.Status == AsyncOperationStatus.Succeeded;
    Addressables.Release(update);
    return updated;
}

배포 전 점검

확인	이유
build Profile과 CDN 환경이 일치	path 불일치로 client가 잘못된 host를 요청하는 것을 막습니다.
새 bundle URL을 client 관점에서 요청	catalog publish 전에 접근 권한·CORS·cache header를 검증합니다.
catalog update 성공·실패·offline 경로	연결 실패가 무한 재시도나 빈 화면으로 가지 않게 합니다.
`GetDownloadSizeAsync`와 `DownloadDependenciesAsync` 테스트	preload 용량과 cache hit/miss UX를 확인합니다.
Content Update Restriction과 변경 asset 비교	update build가 의도한 bundle만 바꾸는지 확인합니다.
이전 catalog/bundle rollback 기록	새 콘텐츠 문제 때 명시적으로 되돌릴 수 있게 합니다.

Addressables 원격 콘텐츠와 profile

Quick Flow

Profile과 Group Inspector

catalog와 cache 운영

배포 전 점검

참고 링크

Opening reference

Addressables 원격 콘텐츠와 profile

Quick Flow

Profile과 Group Inspector

catalog와 cache 운영

배포 전 점검

참고 링크