Huawei AppGallery에 Capacitor 앱을 출시하는 방법

Google Play에 배포하는 것과 동일한 Android 빌드로 Huawei AppGallery에 Capacitor 앱을 게시할 수 있습니다. 무료 HUAWEI Developers 계정을 등록하고, Google Play 서비스에 의존하는 플러그인을 확인하세요(2019년 말 이후 출시된 Huawei 폰에는 해당 서비스가 없습니다). 해당 기능을 숨기거나 대체한 후, AppGallery Connect에 리스팅과 함께 서명된 APK를 업로드하고 심사를 기다리면 됩니다. 이 가이드는 추가 의존성 없이 Google Play 서비스를 감지할 수 있는 작은 네이티브 체크를 앱에 적용하는 방법까지 각 단계를 다룹니다.

AppGallery에 배포해야 하는 대상

AppGallery는 Huawei 스마트폰과 태블릿의 기본 스토어입니다. 다음과 같은 사용자가 있다면 중요합니다:

• 2019년 미국 무역 규제 이후 출시된, Google Play 서비스와 Play Store가 없는 Huawei 기기를 사용하는 유럽·중동·아프리카·라틴 아메리카·동남아시아 사용자.
• Huawei 하드웨어를 표준으로 채택한 기업 또는 정부 고객.

HarmonyOS 관련 참고 사항: 중국 외 지역에서 판매되는 Huawei 스마트폰은 Android 기반 EMUI를 사용하며 APK를 설치할 수 있습니다. 반면 중국 본토에서 HarmonyOS NEXT(HarmonyOS 5 이상)를 실행하는 기기는 네이티브 HarmonyOS 앱만 실행하므로 Android APK는 설치할 수 없습니다. 이 가이드는 Android 기반 AppGallery를 다룹니다.

1단계: Google Play 서비스 의존성 점검

Capacitor 자체는 AndroidX와 자체 Android 라이브러리에만 의존합니다. 위험은 Google 라이브러리를 가져오는 플러그인에서 생깁니다. 의존성을 확인하세요:

cd android
./gradlew :app:dependencies --configuration releaseRuntimeClasspath \
  | grep -E "com.google.android.gms|com.google.firebase|com.google.android.play|billingclient" \
  | sort -u

그 다음, 의존성을 “Google Play 서비스 없이 작동 가능”과 “Google Play 서비스 필요”로 분류하세요.

“동작하지 않음”은 보통 호출이 예외를 던지거나 resolve되지 않는 경우를 뜻합니다. 앱 전체가 크래시하는 일은 드물지만, 심사자가 Huawei 기기에서 테스트할 때 버튼이 먹통이거나 화면이 비어 있으면 흔히 거절 사유가 됩니다.

2단계: 런타임에 Google Play 서비스 감지

Google 의존성을 추가하지 않고도 Android 패키지 매니저에 다음이 설치되어 있는지 물어보면 Google Play 서비스를 확인할 수 있습니다. com.google.android.gms 설치되어 있는지 확인합니다. Capacitor Android 프로젝트에 작은 로컬 플러그인을 추가하세요.

android/app/src/main/java/com/example/app/ServicesCheckPlugin.java:

package com.example.app;

import android.content.pm.PackageManager;
import com.getcapacitor.JSObject;
import com.getcapacitor.Plugin;
import com.getcapacitor.PluginCall;
import com.getcapacitor.PluginMethod;
import com.getcapacitor.annotation.CapacitorPlugin;

@CapacitorPlugin(name = "ServicesCheck")
public class ServicesCheckPlugin extends Plugin {

    private boolean isInstalled(String packageName) {
        try {
            getContext().getPackageManager().getPackageInfo(packageName, 0);
            return true;
        } catch (PackageManager.NameNotFoundException e) {
            return false;
        }
    }

    @PluginMethod
    public void getStatus(PluginCall call) {
        JSObject ret = new JSObject();
        ret.put("gms", isInstalled("com.google.android.gms"));
        ret.put("hms", isInstalled("com.huawei.hwid"));
        call.resolve(ret);
    }
}

다음에 등록하세요: MainActivity.java 첫 번째 제출이 승인되기 super.onCreate:

package com.example.app;

import android.os.Bundle;
import com.getcapacitor.BridgeActivity;

public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        registerPlugin(ServicesCheckPlugin.class);
        super.onCreate(savedInstanceState);
    }
}

Android 11부터 앱은 선언한 다른 패키지만 볼 수 있습니다. 다음을 추가하세요. <queries> 블록을 android/app/src/main/AndroidManifest.xml안에 <manifest>:

<queries>
    <package android:name="com.google.android.gms" />
    <package android:name="com.huawei.hwid" />
</queries>

TypeScript에서 호출하세요:

import { Capacitor, registerPlugin } from '@capacitor/core';

interface ServicesCheckPlugin {
  getStatus(): Promise<{ gms: boolean; hms: boolean }>;
}

const ServicesCheck = registerPlugin<ServicesCheckPlugin>('ServicesCheck');

export async function getMobileServices() {
  if (Capacitor.getPlatform() !== 'android') {
    return { gms: true, hms: false };
  }
  return ServicesCheck.getStatus();
}

패키지 존재 여부는 합리적인 대안입니다. Google Play 서비스가 최신 상태이거나 활성화되어 있는지 알려주지는 않습니다. 이 정보도 필요하면 다음을 추가하세요. com.google.android.gms:play-services-base 그리고 다음을 사용하세요 GoogleApiAvailability.isGooglePlayServicesAvailable(), GMS가 없는 기기에서도 작동합니다.

3단계: 우아하게 디그레이드

결과를 사용해 기능을 켜고 끕니다:

import { PushNotifications } from '@capacitor/push-notifications';
import { getMobileServices } from './services';

export const features = {
  push: true,
  googleSignIn: true,
  playBilling: true,
  inAppReview: true,
};

export async function initFeatures() {
  const { gms } = await getMobileServices();

  features.push = gms;
  features.googleSignIn = gms;
  features.playBilling = gms;
  features.inAppReview = gms;

  if (features.push) {
    const perm = await PushNotifications.requestPermissions();
    if (perm.receive === 'granted') {
      await PushNotifications.register();
    }
  }
}

실용적인 폴백:

• 로그인: Google 버튼을 숨기고 대신 이메일, Apple 또는 Facebook 로그인을 표시하세요. @capgo/capacitor-social-login 을(를) 사용하면 표시하는 프로바이더만 초기화할 수 있습니다.
• 결제: Google Play Billing은 사용할 수 없습니다. AppGallery에는 자체 Huawei IAP가 있습니다. 디지털 구매가 앱의 핵심이라면 Huawei IAP를 통합하거나, 구매 없이 AppGallery 빌드를 배포하고 리스팅에 이를 명시하세요.
• 푸시: HMS 기기의 경우 Huawei Push Kit를 사용하세요. 공식 Capacitor 플러그인은 없으며, Huawei는 Cordova 플러그인을 다음 경로에 게시합니다: @hmscore/* 이 플러그인들은 Capacitor에서 실행되며, Push Kit SDK을 감싸는 작은 네이티브 플러그인을 직접 작성할 수도 있습니다.
• Map: 모든 기기에서 동작하는 WebView 내 웹 맵(Leaflet, MapLibre GL JS)을 사용하거나 Huawei Map Kit를 사용할 수 있습니다.
• 앱 평가하기: Huawei 기기의 경우 Play 리뷰 API를 호출하는 대신 AppGallery 페이지로 링크를 연결하세요.
• 스토어 링크: “앱 업데이트” 버튼은 Play Store가 아닌 Huawei 기기에서 AppGallery(appmarket://details?id=com.example.app)를 열어야 합니다.

실제 Huawei 기기 또는 Huawei의 클라우드 디버깅 서비스에서 테스트하세요. Google API가 포함된 에뮬레이터는 이러한 문제를 모두 숨길 수 있습니다.

4단계: HUAWEI Developers 계정 등록

1. 다음에서 HUAWEI ID를 생성하세요: developer.huawei.com.
2. 전체 신원 인증 개인 또는 기업으로 등록할 수 있습니다. 개인의 경우 신분증과 은행 카드 정보를, 기업의 경우 사업자 등록 서류를 제출해야 합니다. 심사에는 보통 영업일 기준 1~2일이 소요됩니다.
3. 계정 유형과 국가를 신중하게 선택하세요. Huawei는 개인 계정을 기업 계정으로 전환할 수 없으며, 인증된 국가 또는 지역은 나중에 변경할 수 없습니다.

등록은 무료입니다.

5단계: AppGallery Connect에서 앱 생성

1. 열기 AppGallery Connect > 내 앱 > 새 앱.
2. 플랫폼: Android. 기기: 스마트폰 (태블릿도 포함).
3. 앱 이름, 기본 언어 및 패키지 이름. 패키지 이름은 appId 에서 capacitor.config.ts 과 일치해야 하며, 첫 업로드 후에는 변경할 수 없습니다.
4. 앱 카테고리를 선택하세요.

6단계: 릴리스 패키지 빌드 및 서명

AppGallery는 APK와 AAB를 모두 지원합니다. APK 방식이 더 간단합니다. 직접 키로 서명하면 되므로 Huawei가 서명 키를 보유할 필요가 없습니다.

bun run build
bunx cap sync android
cd android
./gradlew assembleRelease

서명 설정: android/app/build.gradle (환경 변수에서 비밀번호를 불러오거나 keystore.properties, 절대 커밋하지 마세요):

android {
    signingConfigs {
        release {
            storeFile file(System.getenv("ANDROID_KEYSTORE_PATH") ?: "upload-keystore.jks")
            storePassword System.getenv("ANDROID_KEYSTORE_PASSWORD")
            keyAlias System.getenv("ANDROID_KEY_ALIAS")
            keyPassword System.getenv("ANDROID_KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

APK는 다음 위치에 있습니다: android/app/build/outputs/apk/release/. keystore가 필요하면 다음 명령이 Android 키스토어 생성기 하나를 생성합니다. 안전하게 보관하세요. 향후 모든 AppGallery 업데이트는 동일한 키로 서명해야 합니다.

대신 AAB를 업로드하는 경우, AppGallery의 App Signing 서비스가 필요합니다. 즉, Play App Signing과 동일한 방식으로 Huawei가 최종 서명 키를 생성하고 보관합니다.

업로드 전 확인 사항:

• versionCode 업로드할 때마다 증가해야 합니다.
• APK의 앱 이름은 AppGallery 목록 이름과 일치해야 합니다.
• 중국 본토 외 지역에 배포하는 경우, 목록에 영어(미국)를 언어로 추가해야 합니다.
• 2026년 9월 30일부터 Android 개발자 인증은 브라질, 인도네시아, 싱가포르, 태국의 인증된 기기에 설치되는 앱에 적용됩니다. Google 서비스가 없는 Huawei 기기는 Google 인증을 받지 않았지만, 동일한 패키지가 인증된 기기에 Google Play 외부 경로로도 설치된다면 Android Developer Console에 패키지 이름을 등록해야 합니다.

7단계: 목록 준비

AppGallery 목록은 Apple, Google과 사양이 다릅니다:

Google Play 로고, 다른 제조사 브랜드가 붙은 Android 기기 프레임, 또는 “Get it on Google Play” 배지가 보이는 스크린샷은 재사용하지 마세요. Huawei는 다른 스토어를 참조하는 목록을 거부합니다. 나머지 에셋은 다른 스토어용으로 만든 것을 재사용하세요. 저희 App Store 및 Google Play 리스팅 가이드 에서 다루고 있습니다.

8단계: 업로드, 제출 및 심사

1. 다음에서 버전 정보 > 초안, 아래에 APK를 업로드하세요 소프트웨어 버전.
2. 상세 정보, 평점, 개인정보 처리방침 및 대상 국가를 입력하세요.
3. 발행 시간을 설정하세요(승인 즉시 또는 예약).
4. 검토를 위해 제출하세요.

검토에는 보통 영업일 기준 며칠이 걸립니다. 반려 시 가이드라인 참조 번호가 포함된 이메일이 발송됩니다. Capacitor 앱에서 흔한 반려 사유는 다음과 같습니다:

• Google Play 서비스 없이 작동하지 않는 기능 (반응 없는 로그인 버튼, 빈 지도 화면 등).
• 중복 앱: 동일한 패키지 이름의 앱이 다른 개발자에 의해 AppGallery에 이미 존재하거나, Huawei가 이전에 Google Play에서 해당 앱을 복사한 경우입니다. 소유권 증빙 자료를 첨부하여 Huawei 개발자 지원에 문의하세요.
• 다른 스토어 참조 스크린샷이나 텍스트에 포함된 경우.
• 영어 버전 누락 국제 배포를 위해.
• 개인정보처리방침 누락되었거나 앱 내부에서 접근할 수 없는 경우.

AppGallery Connect에도 Publishing API이 있으므로, 첫 버전이 라이브로 올라간 후 CI에서 업로드를 자동화할 수 있습니다.

9단계: 빠른 업데이트 유지

모든 네이티브 변경 사항은 다른 스토어와 마찬가지로 Huawei의 재심사를 거칩니다. JavaScript, HTML, CSS 변경 사항은 Capgo Live Update 사용하기 업데이터가 Google Play 서비스를 사용하지 않고 Capgo 엔드포인트에서 번들을 가져오므로, 한 번의 업로드만으로 Huawei, Google, Apple 기기에 설치된 앱에 새 번들을 직접 전달할 수 있습니다. Huawei 빌드에 다른 기능이 있다면 전용 채널을 사용하세요:

bunx @capgo/cli@latest bundle upload --channel huawei

빌드 시점에 Huawei 빌드의 기본 채널을 설정하거나, 앱에서 기기를 해당 채널에 할당할 수 있습니다. Capgo 업데이터 문서 채널과 설정을 설명합니다.

체크리스트

• 의존성 감사 완료, GMS 전용 기능 목록 작성
• 런타임 서비스 체크 추가 및 실제 Huawei 기기에서 테스트 완료
• Google 전용 기능 숨김 또는 대체 (push, sign-in, billing, maps, review)
• HUAWEI Developers 계정 인증 완료
• 동일한 패키지명으로 앱 생성 capacitor.config.ts
• 백업된 keystore로 서명된 Release APK, versionCode bumped
• 아이콘, 스크린샷 3~8개, 간략/상세 소개, 개인정보 처리방침
• 리스팅 자산에 Google Play 관련 내용 포함 금지
• 필요 시 리뷰어용 테스트 계정 제공
• 제출 완료, 심사 이메일 모니터링

Google Play 준비도 병행 중이라면 읽기 Apple 및 Google Play 개발자 계정 생성 방법 해당 규칙은 12명 테스트자 요건이 적용되는 곳에만 해당됩니다.