Come pubblicare un'app Capacitor su Huawei AppGallery

Puoi pubblicare un'app Capacitor su Huawei AppGallery con lo stesso build Android che carichi su Google Play. Registra un account HUAWEI Developers gratuito, controlla quali plugin dipendono dai Google Play services (assenti sui telefoni Huawei usciti da fine 2019), nascondi o sostituisci queste funzionalità, poi carica l'APK firmato su AppGallery Connect con la relativa listing e attendi la review. Questa guida copre ogni passaggio, incluso un piccolo controllo nativo da inserire nell'app per rilevare i Google Play services senza dipendenze extra.

Chi dovrebbe pubblicare su AppGallery

AppGallery è lo store predefinito su telefoni e tablet Huawei. Conta se tra i tuoi utenti ci sono:

• Persone in Europa, Medio Oriente, Africa, America Latina e Sud-est asiatico che usano dispositivi Huawei usciti dopo le restrizioni commerciali USA del 2019, che arrivano senza Google Play services e senza Play Store.
• Clienti enterprise o governativi che hanno adottato hardware Huawei come standard.

Nota su HarmonyOS: i telefoni Huawei venduti fuori dalla Cina continentale utilizzano EMUI, basato su Android e in grado di installare APK. I dispositivi in Cina continentale con HarmonyOS NEXT (HarmonyOS 5 e successivi) eseguono solo app native HarmonyOS, quindi un APK Android non arriva su questi dispositivi. Questa guida riguarda AppGallery nella versione basata su Android.

Passaggio 1: Audit delle dipendenze dai Google Play services

Capacitor dipende solo da AndroidX e dalla propria libreria Android. Il rischio deriva dai plugin che includono librerie Google. Controlla le tue dipendenze:

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

Poi dividile in “funziona senza Google Play services” e “richiede Google Play services”.

«Non funziona» di solito significa che la chiamata genera un errore o non si risolve mai. Raramente fa crashare l'intera app, ma i revisori testano su dispositivi Huawei e un pulsante inattivo o uno schermo vuoto sono motivi di rifiuto comuni.

Passaggio 2: Rileva Google Play services a runtime

Puoi verificare la presenza di Google Play services senza aggiungere dipendenze Google chiedendo al package manager di Android se com.google.android.gms è installato. Aggiungi un piccolo plugin locale al tuo progetto Android Capacitor.

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);
    }
}

Registralo in MainActivity.java prima 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);
    }
}

Da Android 11 in poi, le app vedono solo i pacchetti che dichiarano. Aggiungi un <queries> blocco a android/app/src/main/AndroidManifest.xml, dentro <manifest>:

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

Chiamalo da 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();
}

La presenza del pacchetto è un indicatore ragionevole. Non ti dice se Google Play services è aggiornato o abilitato; se ti serve anche questo, aggiungi com.google.android.gms:play-services-base e usa GoogleApiAvailability.isGooglePlayServicesAvailable(), che funziona anche su dispositivi senza GMS.

Passaggio 3: Degrada in modo controllato

Usa il risultato per attivare o disattivare le funzionalità:

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();
    }
  }
}

Fallback pratici:

• Accedi: nascondi il pulsante Google e mostra invece il login con email, Apple o Facebook. Con @capgo/capacitor-social-login inizializzi solo i provider che mostri.
• Pagamenti: Google Play Billing non è disponibile. AppGallery ha il suo Huawei IAP. Se gli acquisti digitali sono centrali per la tua app, integra Huawei IAP o rilascia la build per AppGallery senza acquisti, specificandolo nella scheda.
• Push: usa Huawei Push Kit per i dispositivi HMS. Non esiste un plugin ufficiale Capacitor; Huawei pubblica plugin Cordova sotto @hmscore/* che girano in Capacitor, oppure puoi scrivere un piccolo plugin nativo attorno all'SDK di Push Kit.
• Mappe: usa una web map (Leaflet, MapLibre GL JS) dentro la WebView, che funziona su ogni dispositivo, oppure Huawei Map Kit.
• Valuta l'app: su Huawei, linka alla tua pagina AppGallery invece di chiamare l'API per le recensioni di Play.
• Link agli store: I pulsanti “Update the app” dovrebbero aprire AppGallery (appmarket://details?id=com.example.app) sui dispositivi Huawei, non il Play Store.

Testa su un dispositivo Huawei reale o sul servizio di cloud debugging di Huawei. Un emulatore con Google APIs nasconderà tutti questi problemi.

Passaggio 4: registra un account HUAWEI Developers

1. Crea un HUAWEI ID su developer.huawei.com.
2. Completa la verifica dell'identità come privato o come azienda. I privati di solito forniscono un documento d'identità e i dati della carta bancaria; le aziende forniscono i documenti di registrazione dell'impresa. La revisione richiede di solito uno o due giorni lavorativi.
3. Scegli con attenzione il tipo di account e il Paese. Huawei non consente di convertire un account privato in un account aziendale e il Paese o la regione verificati non si possono più cambiare in seguito.

La registrazione è gratuita.

Passaggio 5: Crea l'app in AppGallery Connect

1. Apri AppGallery Connect > Le mie app > Nuova app.
2. Piattaforma: Android. Dispositivo: Smartphone (copre anche i tablet).
3. Nome app, lingua predefinita e package name. Il package name deve corrispondere a appId nella capacitor.config.ts e non può essere modificato dopo il primo upload.
4. Scegli la categoria dell'app.

Passaggio 6: Build e firma del pacchetto release

AppGallery accetta APK e AAB. Il percorso APK è più semplice: lo firmi con la tua chiave e Huawei non deve conservare la tua chiave di firma.

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

Configura la firma in android/app/build.gradle (carica le password da variabili d'ambiente o keystore.properties, non commetterle mai):

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
        }
    }
}

L'APK si trova in android/app/build/outputs/apk/release/. Se ti serve un keystore, il Generatore di keystore per Android ne crea uno. Tienilo al sicuro: ogni futuro aggiornamento su AppGallery deve essere firmato con la stessa chiave.

Se invece carichi un AAB, AppGallery richiede il suo servizio App Signing, il che significa che Huawei genera e conserva la chiave di firma finale, lo stesso modello di Play App Signing.

Alcune cose da verificare prima del caricamento:

• versionCode deve aumentare a ogni caricamento.
• Il nome dell'app nell'APK deve corrispondere al nome della scheda su AppGallery.
• Se distribuisci al di fuori della Cina continentale, indica l'inglese (US) come lingua nella scheda.
• Dal 30 settembre 2026, la verifica degli sviluppatori Android si applica alle app installate su dispositivi certificati in Brasile, Indonesia, Singapore e Thailandia. I dispositivi Huawei senza servizi Google non sono certificati Google, ma se lo stesso package viene installato anche al di fuori di Google Play su dispositivi certificati, registra il package name nella Android Developer Console.

Passaggio 7: Prepara la scheda

La scheda di AppGallery ha specifiche proprie, diverse da quelle di Apple e Google:

Non riutilizzare screenshot che mostrano il logo di Google Play, cornici di dispositivi Android con il marchio di altri produttori o badge “Get it on Google Play”. Huawei rifiuta le schede che fanno riferimento ad altri store. Per il resto degli asset, riutilizza quelli creati per gli altri store; il nostro Guida alla pubblicazione su App Store e Google Play li copre.

Passaggio 8: Upload, invio e revisione

1. In Informazioni versione > Bozza, carica l'APK sotto Versione software.
2. Compila i dettagli della scheda, il rating, la privacy e i paesi.
3. Imposta l'orario di rilascio (immediato dopo l'approvazione o programmato).
4. Invia per la revisione.

La revisione richiede di solito qualche giorno lavorativo. In caso di rifiuto, ricevi un'email con il riferimento alla linea guida. I motivi più comuni per le app Capacitor:

• Funzionalità che non funzionano senza i Google Play services (pulsante di login che non fa nulla, schermata mappa vuota).
• App duplicata: un'app con lo stesso package name esiste già su AppGallery di un altro sviluppatore, o Huawei ha copiato la tua app da Google Play. Contatta l'assistenza sviluppatori Huawei con la prova di proprietà.
• Altri riferimenti agli store negli screenshot o nel testo.
• Manca l'inglese per la distribuzione internazionale.
• Informativa sulla privacy mancante o non raggiungibile dall'app.

AppGallery Connect ha anche una API di Publishing, così puoi automatizzare gli upload dalla CI una volta che la prima versione è online.

Passaggio 9: Mantieni gli aggiornamenti rapidi

Ogni modifica nativa deve passare di nuovo per la revisione Huawei, come negli altri store. Per le modifiche a JavaScript, HTML e CSS, Live updates di Capgo distribuisci il nuovo bundle direttamente alle app installate su dispositivi Huawei, Google e Apple con un solo upload, poiché l'updater recupera i bundle dal tuo endpoint Capgo e non usa i Google Play services. Usa un canale dedicato se la tua build Huawei ha funzionalità diverse:

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

Imposta il canale predefinito per la build Huawei in fase di build, o assegna i dispositivi al canale dalla tua app. La documentazione dell'updater Capgo spiega i canali e la configurazione.

Checklist

• Audit delle dipendenze completato, elenco delle funzionalità solo GMS
• Controllo dei servizi runtime aggiunto e testato su un dispositivo Huawei reale
• Funzionalità solo Google nascoste o sostituite (push, sign-in, billing, maps, review)
• Account HUAWEI Developers verificato
• App creata con lo stesso package name di capacitor.config.ts
• Rilascia l'APK firmato con un keystore di backup, versionCode incrementato
• Icona, da 3 a 8 screenshot, intro breve e completa, privacy policy
• Nessun riferimento a Google Play negli asset della scheda
• Account di test per i revisori, se necessario
• Inviato, monitoraggio email di revisione

Se stai preparando anche Google Play, leggi come creare account developer Apple e Google Play per la regola dei 12 tester che vale solo lì.