Cordova Client SDK

Článek
07/19/2023

Důležité

Visual Studio App Center je naplánované k vyřazení na 31. března 2025. I když můžete Visual Studio App Center dál používat, dokud ho úplně nevyřadíte, existuje několik doporučených alternativ, na které můžete migraci zvážit.

Přečtěte si další informace o časových osách a alternativách podpory.

Tento modul plug-in poskytuje integraci služby CodePush na straně klienta a umožňuje snadné přidání dynamické aktualizace aplikací Cordova.

Poznámka

Podpora aplikací Cordova skončila v dubnu 2022. Další informace najdete v blogu app center.

Jak to funguje?

Aplikace Cordova se skládá ze souborů HTML, CSS a JavaScriptu a všech doprovodných obrázků, které jsou společně spojeny pomocí rozhraní příkazového řádku Cordovy a distribuovány jako součást binárního souboru specifického pro danou platformu (tj. souboru .ipa nebo .apk). Po vydání aplikace bude aktualizace kódu nebo prostředků obrázku vyžadovat překompilování a redistribuci celého binárního souboru. Tento proces zahrnuje čas kontroly obchodů, do kterých publikujete.

Modul plug-in CodePush pomáhá okamžitě vylepšovat produkty před vašimi koncovými uživateli tím, že udržuje kód a obrázky synchronizované s aktualizacemi, které vydáváte na server CodePush. Díky tomu vaše aplikace získá výhody offline mobilního prostředí a také agilitu aktualizací, která se podobá webu, a to hned, jak budou k dispozici. Je to win-win!

Aby se zajistilo, že koncoví uživatelé budou mít vždy funkční verzi vaší aplikace, modul plug-in CodePush udržuje kopii předchozí aktualizace, takže v případě, že omylem nasdílíte aktualizaci, která obsahuje chybu, se může automaticky vrátit zpět. Díky tomu si můžete být jistí, že nově nalezené verze nebudou uživatelé zablokovaní, než budete mít možnost vrátit se zpět na server. Je to win-win-win!

Poznámka

Žádné změny produktů, které se dotýkají nativního kódu (např. upgrade verzí Cordovy nebo přidání nového modulu plug-in), se nedají distribuovat prostřednictvím CodePush, a proto se musí aktualizovat prostřednictvím příslušných obchodů.

Podporované platformy Cordova

Cordova 5.0.0+ je plně podporovaná, společně s následujícími přidruženými platformami:

Android (cordova-android 4.0.0+) - Včetně CrossWalk!
iOS (cordova-ios 3.9.0+) – (Pokud chcete spolu s modulem cordova-plugin-wkwebview-engine plug-in používat CodePush, musíte nainstalovat v1.5.1-beta+, který zahrnuje plnou podporu aplikací využívajících webView.)

Pokud chcete zkontrolovat verze jednotlivých platforem Cordovy, které aktuálně používáte, můžete spustit následující příkaz a zkontrolovat Installed platforms seznam:

    cordova platform ls

Pokud používáte starší platformu Android nebo iOS, než je uvedeno výše, a mohli byste ji upgradovat, můžete to snadno provést spuštěním následujících příkazů (v případě potřeby platformu vynecháte):

    cordova platform update android
    cordova platform update ios

Začínáme

Poznámka

Tento článek obsahuje odkazy na termín seznam povolených, což je termín, který už Microsoft nepoužívá. Po odebrání termínu ze softwaru ho z tohoto článku odebereme.

Jakmile budete postupovat podle obecných pokynů "Začínáme" pro nastavení účtu CodePush, můžete spustit CodePush-ifying aplikaci Cordova spuštěním následujícího příkazu z kořenového adresáře vaší aplikace:

cordova plugin add cordova-plugin-code-push@latest

S nainstalovaným modulem plug-in CodePush nakonfigurujte aplikaci tak, aby ho používala, pomocí následujících kroků:

Přidejte klíče nasazení do config.xml souboru a nezapomeňte zahrnout správný klíč pro každou platformu Cordova:

    <platform name="android">
        <preference name="CodePushDeploymentKey" value="YOUR-ANDROID-DEPLOYMENT-KEY" />
    </platform>
    <platform name="ios">
        <preference name="CodePushDeploymentKey" value="YOUR-IOS-DEPLOYMENT-KEY" />
    </platform>

Připomínáme, že tyto klíče se pro vás vygenerují při vytváření aplikace CodePush prostřednictvím rozhraní příkazového řádku. Pokud je potřebujete načíst, můžete spustit appcenter codepush deployment list -a <ownerName>/<appName> --displayKeysa získat klíč pro konkrétní nasazení, které chcete použít (např. Staging, ). Production

Důležité

Doporučujeme vytvořit samostatnou aplikaci CodePush pro iOS a Android, což je důvod, proč výše uvedená ukázka deklaruje samostatné klíče pro Android a iOS. Pokud vyvíjíte pouze pro jednu platformu, stačí zadat klíč nasazení pro Android nebo iOS, abyste nemuseli přidávat další <platform> prvek, jak je znázorněno výše.

Od verze 1.10.0 můžete podepisovat sady aktualizací (další informace o podepisování kódu najdete v příslušné dokumentaci). Pokud chcete povolit podepisování kódu pro aplikaci Cordova, měli byste nastavit veřejný klíč pro ověření podpisu sady zadáním následujícího preference nastavení v config.xmlsouboru :

    <platform name="android">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>
    <platform name="ios">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>

Pro každou platformu můžete použít stejný pár privátního a veřejného klíče.

Pokud v souboru config.xml používáte prvek<access origin="*" />, znamená to, že vaše aplikace už může komunikovat se servery CodePush a tento krok můžete bezpečně přeskočit. V opačném případě přidejte následující další <access /> prvky:

    <access origin="https://codepush.appcenter.ms" />
    <access origin="https://codepush.blob.core.windows.net" />
    <access origin="https://codepushupdates.azureedge.net" />

Pokud chcete zajistit, že vaše aplikace bude mít přístup k serveru CodePush na platformách kompatibilních s CSP, přidejte https://codepush.appcenter.ms do značky Content-Security-Policymeta v index.html souboru :

    <meta http-equiv="Content-Security-Policy" content="default-src https://codepush.appcenter.ms 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *" />

Nakonec pečlivě zkontrolujte, že už máte modul plug-in cordova-plugin-whitelist nainstalovaný (většina aplikací). Zkontrolujte to spuštěním následujícího příkazu:

    cordova plugin ls

Pokud cordova-plugin-whitelist je v seznamu, můžete začít. Jinak ho přidejte spuštěním následujícího příkazu:

    cordova plugin add cordova-plugin-whitelist

Teď jste připraveni použít modul plug-in v kódu aplikace. Příklady najdete v ukázkových aplikacích a další podrobnosti najdete v dokumentaci k rozhraní API.

Použití modulu plug-in

Když máte nainstalovaný a nakonfigurovaný modul plug-in CodePush, zbývá do aplikace přidat potřebný kód, který bude řídit následující zásady:

Kdy (a jak často) vyhledat aktualizaci? (e.g. app spuštění, v reakci na kliknutí na tlačítko na stránce nastavení, pravidelně v určitém pevném intervalu)
Když je k dispozici aktualizace, jak ji prezentovat koncovému uživateli? Nejjednodušší způsob, jak to udělat, je spustit v obslužné rutině deviceready události vaší aplikace následující:

codePush.sync();

Pokud je k dispozici aktualizace, bude bezobslužně stažena a nainstalována při příštím restartování aplikace (ať už explicitně koncovým uživatelem nebo operačním systémem), což zajistí co nejméně invazivní prostředí pro koncové uživatele. Pokud je dostupná aktualizace povinná, nainstaluje se okamžitě, aby ji koncový uživatel získal co nejdříve.

Pokud chcete, aby vaše aplikace rychleji objevoval aktualizace, můžete také zvolit volání sync pokaždé, když se aplikace obnoví z pozadí, a to přidáním následujícího kódu (nebo podobného kódu) jako součásti chování aplikace při spuštění. Můžete volat sync tak často, jak chcete, takže to, kdy a kam budete volat, závisí na vašich osobních preferencích.

document.addEventListener("resume", function () {
    codePush.sync();
});

Pokud navíc chcete zobrazit dialogové okno pro potvrzení aktualizace ("aktivní instalace"), nakonfigurovat, kdy se nainstaluje dostupná aktualizace (např. vynutit okamžité restartování) nebo nějakým způsobem přizpůsobit prostředí aktualizace, přečtěte sync si referenční informace k rozhraní API metody, kde najdete informace o tom, jak toto výchozí chování upravit.

Důležité

I když vývojářská smlouva společnosti Apple plně umožňuje aktualizace JavaScriptu a prostředků (což je to, co umožňuje CodePush!), je to v rozporu s jejich zásadami, aby aplikace zobrazovala výzvu k aktualizaci. Z tohoto důvodu doporučujeme, aby App Store distribuované aplikace tuto možnost při volání syncnepovolilyupdateDialog, zatímco Google Play a interně distribuované aplikace (např. Enterprise, Fabric, HockeyApp) ji můžou povolit nebo přizpůsobit.

Vydává se Aktualizace

Jakmile je vaše aplikace nakonfigurovaná a distribuovaná uživatelům a provedete nějaké změny kódu nebo prostředků, je čas je okamžitě uvolnit. Nejjednodušší (a doporučený) způsob, jak to udělat, je použít release-cordova příkaz v rozhraní příkazového řádku CodePush, který zpracovává přípravu a vydání aktualizace na server CodePush.

Poznámka

Než začnete vydávat aktualizace, přihlaste se k App Center spuštěním příkazu .appcenter login

Ve své nejzásadnější podobě tento příkaz vyžaduje pouze jeden parametr: jméno vlastníka + "/" + název aplikace.

appcenter codepush release-cordova -a <ownerName>/<appName>
appcenter codepush release-cordova -a <ownerName>/MyApp-ios
appcenter codepush release-cordova -a <ownerName>/MyApp-android

Tip

Při použití funkce rozhraní příkazového řádku set-current app center nemusíte k určení aplikace, na kterou je příkaz směrován, používat příznak -a.

Tip

Při vydávání aktualizací CodePush nemusíte verzi aplikace v config.xml souboru narážet, protože binární verzi vůbec neupravujete. Tuto verzi stačí narazit pouze při upgradu Cordovy nebo některého z modulů plug-in. V takovém okamžiku budete muset vydat aktualizaci nativních obchodů. CodePush automaticky vygeneruje "popisek" pro každou verzi, kterou vytvoříte (např. v3), aby ho bylo možné identifikovat v historii verzí.

Příkaz release-cordova umožňuje takový jednoduchý pracovní postup, protože rozumí standardnímu rozložení aplikace Cordova, takže může vygenerovat aktualizaci a přesně vědět, které soubory se mají nahrát. Pro podporu flexibilních strategií vydávání verzí navíc příkaz zveřejňuje řadu volitelných parametrů, release-cordova které umožňují přizpůsobit způsob distribuce aktualizace koncovým uživatelům (například které binární verze jsou s ní kompatibilní? Má být verze považována za povinnou?).

# Release a mandatory update with a changelog
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -m --description "Modified the header color"

# Release a dev Android build to 1/4 of your end users
appcenter codepush release-cordova -a <ownerName>/MyApp-android --rollout 25

# Release an update that targets users running any 1.1.* binary, as opposed to
# limiting the update to exact version name in the config.xml file
appcenter codepush release-cordova -a <ownerName>/MyApp-android --target-binary-version "~1.1.0"

# Release the update now but mark it as disabled
# so that no users can download it yet
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -x

Klient CodePush podporuje rozdílové aktualizace, takže i když při každé aktualizaci vydáváte kód aplikace, koncoví uživatelé si ve skutečnosti stáhnou jenom soubory, které potřebují. Služba to zpracovává automaticky, takže se můžete soustředit na vytváření skvělých aplikací a my se můžeme starat o optimalizaci stahování koncovými uživateli.

Další podrobnosti o tom, jak release-cordova příkaz funguje, a o různých parametrech, které zveřejňuje, najdete v dokumentaci k rozhraní příkazového řádku. Pokud navíc chcete, aby se spuštění cordova prepare příkazu zpracovávalo sami, a proto chcete ještě flexibilnější řešení než release-cordova, podívejte se na release příkaz , kde najdete další podrobnosti.

Pokud narazíte na nějaké problémy nebo budete mít jakékoli dotazy, komentáře nebo názory, můžete nám poslat e-mail nebo otevřít nový problém v tomto úložišti a my odpovíme co nejdříve. Podívejte se také na nápovědu a zpětnou vazbu.

Reference rozhraní API

Rozhraní CodePush API se pro vaši aplikaci zpřístupní prostřednictvím globálního codePush objektu, který je k dispozici po spuštění deviceready události. Toto rozhraní API zveřejňuje následující metody nejvyšší úrovně:

checkForUpdate: Zeptá se služby CodePush, jestli má nakonfigurované nasazení aplikace k dispozici aktualizaci.
getCurrentPackage: Načte metadata o aktuálně nainstalované aktualizaci (např. popis, čas instalace, velikost).
getPendingPackage: Načte metadata aktualizace (pokud existuje), která byla stažena a nainstalována, ale ještě nebyla použita při restartování.
notifyApplicationReady: Upozorní modul runtime CodePush, že se nainstalovaná aktualizace považuje za úspěšnou. Pokud ručně kontrolujete a instalujete aktualizace (tj. nepoužíváte metodu synchronizace, abyste to všechno zvládli za vás), pak tato metoda MUSÍ být volána; v opačném případě CodePush bude považovat aktualizaci za neúspěšnou a při příštím restartování aplikace se vrátí k předchozí verzi.
restartApplication: Okamžitě restartuje aplikaci. Pokud čeká na aktualizaci, zobrazí se okamžitě koncovému uživateli.
synchronizace: Umožňuje vyhledat aktualizaci, stáhnout ji a nainstalovat, a to vše jediným voláním. Pokud nepotřebujete vlastní uživatelské rozhraní nebo chování, doporučujeme, aby většina vývojářů při integraci CodePush do svých aplikací používala tuto metodu.

Kromě toho jsou následující objekty a výčty také zpřístupněny globálně jako součást rozhraní CodePush API:

InstallMode: Definuje dostupné režimy instalace aktualizací.
LocalPackage: Obsahuje informace o místně nainstalovaném balíčku.
RemotePackage: Obsahuje informace o balíčku aktualizace, který je k dispozici ke stažení.
SyncStatus: Definuje možné přechodné a výsledné stavy operace synchronizace .

codePush.checkForUpdate

codePush.checkForUpdate(onSuccess, onError?, deploymentKey?: String);

Dotazuje službu CodePush a zjistí, jestli má nakonfigurované nasazení aplikace k dispozici aktualizaci. Ve výchozím nastavení použije klíč nasazení, který je nakonfigurovaný v souboruconfig.xml , ale můžete ho přepsat zadáním hodnoty prostřednictvím volitelného deploymentKey parametru. To může být užitečné v případě, že chcete uživatele dynamicky "přesměrovat" na konkrétní nasazení, jako je povolení dřívějšího přístupu prostřednictvím velikonočního vejce nebo přepínače nastavení uživatele.

Po dokončení kontroly aktualizace se aktivuje onUpdateCheck zpětné volání s jednou ze dvou možných hodnot:

null pokud není k dispozici žádná aktualizace. K tomu dochází v následujících scénářích:
- Nakonfigurované nasazení neobsahuje žádné verze, takže není co aktualizovat.
- Nejnovější verze v rámci nakonfigurovaného nasazení cílí na jinou binární verzi, než jakou právě používáte (starší nebo novější).
- Aktuálně spuštěná aplikace už má nejnovější verzi z nakonfigurovaného nasazení, takže tuto verzi znovu nepotřebuje.
Instance RemotePackage , která představuje dostupnou aktualizaci, kterou lze zkontrolovat a později stáhnout.

Parametry:

onSuccess: Zpětné volání, které se vyvolá při přijetí úspěšné odpovědi ze serveru. Zpětné volání obdrží jeden parametr, který je popsán výše.
onError: Volitelné zpětné volání, které se vyvolá v případě chyby. Zpětné volání přebírá jeden parametr chyby, který obsahuje podrobnosti o chybě.
deploymentKey: Volitelný klíč nasazení, který přepíše nastaveníconfig.xml .

Příklad použití:

codePush.checkForUpdate(function (update) {
    if (!update) {
        console.log("The app is up to date.");
    } else {
        console.log("An update is available! Should we download it?");
    }
});

codePush.getCurrentPackage

codePush.getCurrentPackage(onSuccess, onError?);

Načte metadata o aktuálně nainstalovaném balíčku (např. popis, čas instalace). To může být užitečné ve scénářích, jako je zobrazení dialogového okna "Co je nového?" po použití aktualizace nebo kontrola, jestli existuje čekající aktualizace, která čeká na použití prostřednictvím obnovení nebo restartování.

Po dokončení načítání aktualizace se aktivuje onSuccess zpětné volání s jednou ze dvou možných hodnot:

null pokud aplikace aktuálně spouští úvodní stránku HTML z binárního souboru, a ne aktualizaci CodePush. K tomu dochází v následujících scénářích:
- Koncový uživatel nainstaloval binární soubor aplikace a ještě si musí nainstalovat aktualizaci CodePush.
- Koncový uživatel nainstaloval aktualizaci binárního souboru (např. z úložiště), která vymazal staré aktualizace CodePush a dal přednost binárnímu souboru.
Instance LocalPackage , která představuje metadata pro aktuálně spuštěnou aktualizaci CodePush.

Parametry:

onSuccess: Zpětné volání, které se vyvolá při přijetí metadat o aktuálně spuštěné aktualizaci. Zpětné volání obdrží jeden parametr, který je popsán výše.
onError: Volitelné zpětné volání, které se vyvolá v případě chyby. Zpětné volání přebírá jeden parametr chyby, který obsahuje podrobnosti o chybě.

Příklad použití:

codePush.getCurrentPackage(function (update) {
    if (!update) {
        console.log("No updates have been installed");
        return;
    }

    // If the current app "session" represents the first time
    // this update has run, and it had a description provided
    // with it upon release, let's show it to the end user
    if (update.isFirstRun && update.description) {
        // Display a "what's new?" modal
    }
});

codePush.getPendingPackage

codePush.getPendingPackage(onSuccess, onError?);

Získá metadata pro aktuálně čekající aktualizaci (pokud existuje). Aktualizace se považuje za čekající, pokud byla stažena a nainstalována, ale ještě nebyla použita při restartování aplikace. Aktualizace může být v tomto stavu pouze v případě, že InstallMode.ON_NEXT_RESUMEInstallMode.ON_NEXT_RESTART nebo byla zadána při volání sync nebo LocalPackage.install, a aplikace ještě nebyla restartována nebo obnovena (v uvedeném pořadí). Tato metoda může být užitečná, pokud chcete zjistit, jestli existuje čekající aktualizace, a pak uživatele vyzvat, pokud chce okamžitě restartovat (přes codePush.restartApplication), aby ji použil.

Po dokončení načítání aktualizace se aktivuje onSuccess zpětné volání s jednou ze dvou možných hodnot:

null pokud aplikace aktuálně nemá čekající aktualizaci (např. aplikace už používá nejnovější dostupnou verzi).
Instance LocalPackage , která představuje metadata pro aktuálně čekající aktualizaci CodePush.

Parametry:

onSuccess: Zpětné volání, které se vyvolá při přijetí metadat o aktuálně čekající aktualizaci. Zpětné volání obdrží jeden parametr, který je popsán výše.
onError: Volitelné zpětné volání, které se vyvolá v případě chyby. Zpětné volání přebírá jeden parametr chyby, který obsahuje podrobnosti o chybě.

Příklad použití:

codePush.getPendingPackage(function (update) {
    if (update) {
        // An update is currently pending, ask the
        // user if they want to restart
    }
});

codePush.notifyApplicationReady

codePush.notifyApplicationReady(notifySucceeded?, notifyFailed?);

Upozorní modul runtime CodePush, že čerstvě nainstalovaná aktualizace by měla být považována za úspěšnou, takže automatické vrácení zpět na straně klienta není nutné. Tuto funkci je povinné volat někde v kódu aktualizované sady. V opačném případě při dalším restartování aplikace modul runtime CodePush předpokládá, že nainstalovaná aktualizace selhala, a vrátí se k předchozí verzi. Toto chování pomáhá zajistit, aby koncoví uživatelé nebyli blokovaní chybnou aktualizací.

Pokud používáte sync funkci a provádíte kontrolu aktualizací při spuštění aplikace, nemusíte volat ručně notifyApplicationReady , protože sync ji zavoláte za vás. Toto chování existuje z předpokladu, že při zavolání sync ve vaší aplikaci představuje dobrou aproximaci úspěšného spuštění.

Parametry:

notifySucceeded: Volitelné zpětné volání vyvoláno, pokud byl modul plug-in úspěšně upozorněn.
notifyFailed: Volitelné zpětné volání vyvoláno, pokud dojde k chybě s oznámením modulu plug-in.

codePush.restartApplication

codePush.restartApplication();

Okamžitě aplikaci restartuje. Tato metoda je určená pro pokročilé scénáře a je primárně užitečná, pokud jsou splněny následující podmínky:

Vaše aplikace určuje hodnotu ON_NEXT_RESTARTON_NEXT_RESUME režimu instalace nebo při volání sync metod nebo LocalPackage.install . Tím se aktualizace neaplikuje, dokud se aplikace nerestartuje (koncovým uživatelem nebo operačním systémem) nebo dokud se neobnoví, takže se aktualizace koncovému uživateli okamžitě nezobrazí.
Máte událost uživatele specifickou pro aplikaci (například koncový uživatel přecházený zpět na domovskou trasu aplikace), která vám umožní aktualizaci použít nenápadným způsobem a potenciálně se aktualizace před koncovým uživatelem dostane dříve, než bude čekat na další restartování nebo obnovení.

codePush.sync

codePush.sync(syncCallback?, syncOptions?, downloadProgress?, syncErrback?);

Synchronizuje kód a image vaší aplikace s nejnovější verzí s nakonfigurovaným nasazením. checkForUpdate Na rozdíl od metody, která kontroluje přítomnost aktualizace a umožňuje řídit, co dělat dál, sync zpracovává kontrolu aktualizací, stahování a instalaci za vás.

Tato metoda poskytuje podporu pro dva různé (ale přizpůsobitelné) "režimy", které umožňují snadno povolit aplikace s různými požadavky:

Bezobslužný režim(výchozí chování), který automaticky stáhne dostupné aktualizace a použije je při příštím restartování aplikace (např. operační systém nebo koncový uživatel ji ukončil nebo se zařízení restartovalo). Tímto způsobem bude celé prostředí aktualizace pro koncového uživatele "tiché", protože se mu nezobrazují žádné výzvy k aktualizaci nebo se nerestartuje "syntetická" aplikace.
Aktivní režim, který, když je aktualizace k dispozici, vyzve koncového uživatele před stažením k oprávnění a okamžitě aktualizaci použije. Pokud byla aktualizace vydána pomocí povinného příznaku, koncový uživatel bude stále upozorněn na aktualizaci, ale nebude mít možnost ji ignorovat.

Příklad použití:

// Fully silent update that keeps the app in
// sync with the server, without ever
// interrupting the end user
codePush.sync();

// Active update that lets the end user know
// about each update, and displays it to them
// immediately after downloading it
codePush.sync(null, { updateDialog: true, installMode: InstallMode.IMMEDIATE });

Tip

Pokud se chcete rozhodnout, jestli zkontrolujete nebo stáhnete dostupnou aktualizaci na základě úrovně baterie zařízení koncového uživatele, stavu sítě atd., zabalte volání synchronizace do stavu, který zajistí, že ho budete volat jenom v případě potřeby.

I když se metoda synchronizace snaží usnadnit provádění tichých a aktivních aktualizací s malou konfigurací, přijímá následující volitelné parametry, které umožňují přizpůsobit řadu aspektů výchozího chování uvedeného výše:

syncCallback: Volá se, když se proces synchronizace přesune z jedné fáze do druhé v celkovém procesu aktualizace. Metoda je volána se stavovým kódem, který představuje aktuální stav a může být libovolnou SyncStatus z hodnot.
syncOptions: Volitelný SyncOptions parametr, který konfiguruje chování operace synchronizace.
downloadProgress: Volá se pravidelně při stahování dostupné aktualizace ze serveru CodePush. Metoda je volána s objektem DownloadProgress , který obsahuje následující dvě vlastnosti:
- totalBytes(Number) – celkový počet bajtů očekávaných pro tuto aktualizaci (tj. velikost sady souborů, které se změnily od předchozí verze).
- receivedBytes(Number) – počet dosud stažených bajtů, který lze použít ke sledování průběhu stahování.
syncErrback: Volá se, když dojde k chybě v některém z interních kroků synchronizace. Metoda je volána se standardním javascriptovým Error objektem jako prvním argumentem.

Možnosti synchronizace

I když se sync metoda snaží usnadnit provádění tichých a aktivních aktualizací s malou konfigurací, přijímá objekt "options", který umožňuje přizpůsobit mnoho aspektů výchozího chování uvedené výše:

deploymentKey(String) – určuje klíč nasazení, se který chcete dotazovat na aktualizaci. Ve výchozím nastavení je tato hodnota odvozena ze souboru config.xml , ale tato možnost umožňuje ji přepsat ze strany skriptu, pokud potřebujete dynamicky použít jiné nasazení pro konkrétní volání sync.
installMode(InstallMode) – určuje, kdy chcete nainstalovat volitelné aktualizace (tj. ty, které nejsou označené jako povinné). Výchozí hodnota je InstallMode.ON_NEXT_RESTART. Popis dostupných možností a jejich funkce najdete v InstallMode referenčních informacích k výčtu.
mandatoryInstallMode(InstallMode) – Určuje, kdy chcete nainstalovat aktualizace, které jsou označené jako povinné. Výchozí hodnota je InstallMode.IMMEDIATE. Popis dostupných možností a jejich funkce najdete v InstallMode referenčních informacích k výčtu.
minimumBackgroundDuration(Number) – určuje minimální počet sekund, po který bude aplikace před restartováním aplikace na pozadí. Tato vlastnost se vztahuje pouze na aktualizace, které se instalují pomocí InstallMode.ON_NEXT_RESUMEnástroje , a může být užitečná k tomu, abyste aktualizaci získali před koncovými uživateli dříve, aniž by byla příliš rušivá. Výchozí hodnota je 0, která použije aktualizaci okamžitě po obnovení, i když byla na pozadí.
ignoreFailedUpdates(Logická hodnota) – určuje, jestli se má dostupná aktualizace ignorovat, pokud byla dříve nainstalována a vrácena zpět na klientovi (protože notifyApplicationReady nebyla úspěšně volána). Výchozí hodnota je true.
updateDialog(UpdateDialogOptions) – objekt "options", který slouží k určení, jestli se má koncovému uživateli zobrazit potvrzovací dialogové okno, když je k dispozici aktualizace, a pokud ano, jaké řetězce se mají použít. Výchozí hodnota je null, která zakáže dialogové okno. Nastavení na libovolnou true hodnotu povolí dialogové okno s výchozími řetězci a předání objektu tomuto parametru umožní povolit dialogové okno a také přepíše jeden nebo více výchozích řetězců.

Následující seznam obsahuje dostupné možnosti a jejich výchozí hodnoty:

appendReleaseDescription(Boolean) – označuje, jestli chcete připojit popis dostupné verze ke zprávě oznámení, která se zobrazí koncovému uživateli. Výchozí hodnota je false.
descriptionPrefix(String) – označuje řetězec, se kterým chcete při zobrazení oznámení o aktualizaci koncovému uživateli přidat předponu k popisu verze (pokud existuje). Výchozí hodnota je " Description: ".
mandatoryContinueButtonLabel(String): Text, který se má použít pro tlačítko, které musí koncový uživatel stisknout, aby nainstaloval povinnou aktualizaci. Výchozí hodnota je "Continue".
mandatoryUpdateMessage(String) – text použitý jako text oznámení o aktualizaci, když je aktualizace určená jako povinná. Výchozí hodnota je "An update is available that must be installed.".
optionalIgnoreButtonLabel(String) – text, který se má použít pro tlačítko, které může koncový uživatel stisknout, aby ignoroval volitelnou aktualizaci, která je k dispozici. Výchozí hodnota je "Ignore".
optionalInstallButtonLabel(String) – text, který se má použít pro tlačítko, které může koncový uživatel stisknout a nainstalovat volitelnou aktualizaci. Výchozí hodnota je "Install".
optionalUpdateMessage(String) – text použitý jako text oznámení o aktualizaci, pokud je aktualizace volitelná. Výchozí hodnota je "An update is available. Would you like to install it?". *- updateTitle(String) – text použitý jako záhlaví oznámení o aktualizaci, které se zobrazí koncovému uživateli. Výchozí hodnota je "Update available".

Příklad použití:

// Download the update silently, but install it on
// the next resume, as long as at least 5 minutes
// has passed since the app was put into the background.
codePush.sync(null, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 60 * 5 });

// Download the update silently, and install optional updates
// on the next restart, but install mandatory updates on the next resume.
codePush.sync(null, { mandatoryInstallMode: InstallMode.ON_NEXT_RESUME });

// Changing the title displayed in the
// confirmation dialog of an "active" update
codePush.sync(null, { updateDialog: { title: "An update is available!" } });

// Displaying an update prompt that includes the
// description for the CodePush release
codePush.sync(null, {
   updateDialog: {
    appendReleaseDescription: true,
    descriptionPrefix: "\n\nChange log:\n"
   },
   installMode: InstallMode.IMMEDIATE
});

// Silently check for the update, but
// display a custom downloading UI
// via the SyncStatus and DownloadProgress callbacks
codePush.sync(syncStatus, null, downloadProgress);

function syncStatus(status) {
    switch (status) {
        case SyncStatus.DOWNLOADING_PACKAGE:
            // Show "downloading" modal
            break;
        case SyncStatus.INSTALLING_UPDATE:
            // Hide "downloading" modal
            break;
    }
}

function downloadProgress(downloadProgress) {
    if (downloadProgress) {
    	// Update "downloading" modal with current download %
        //console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes);
    }
}

Metodu sync lze volat kdekoli, kde chcete vyhledat aktualizaci. To může být v obslužné deviceready rutině události, click události tlačítka, ve zpětném volání pravidelného časovače nebo v čemkoli jiném, co dává smysl pro vaše potřeby. Stejně jako metoda checkForUpdate spustí síťový požadavek na kontrolu aktualizace na pozadí, aby to nemělo vliv na odezvu vlákna uživatelského rozhraní nebo vlákna JavaScriptu.

Objekty balíčků

Metody checkForUpdate a getCurrentPackage vyvolávají úspěšná volání, která při aktivaci poskytují přístup k objektům "package". Balíček představuje aktualizaci kódu a také všechna další metadata (např. popis, povinné?). Rozhraní API CodePush rozlišuje mezi následujícími typy balíčků:

LocalPackage: Představuje staženou aktualizaci, která už je spuštěná nebo je nainstalovaná a čeká na restartování aplikace.
RemotePackage: Představuje dostupnou aktualizaci na serveru CodePush, která ještě nebyla stažena.

Balíček localpackage

Obsahuje podrobnosti o aktualizaci, která byla stažena místně nebo již nainstalována. Odkaz na instanci tohoto objektu můžete získat buď voláním codePush.getCurrentPackage metody, nebo jako hodnotu poskytnutou pro úspěšné RemotePackage.download volání metody.

Vlastnosti

appVersion: Nativní verze aplikace, pro která je tato aktualizace balíčku určená. (Řetězec)
deploymentKey: Klíč nasazení balíčku. (Řetězec)
description: Popis aktualizace. Jedná se o stejnou hodnotu, kterou jste zadali v rozhraní příkazového řádku při vydání aktualizace. (Řetězec)
failedInstall: Označuje, jestli byla tato aktualizace dříve nainstalována, ale byla vrácena zpět. Metoda sync bude automaticky ignorovat aktualizace, které dříve selhaly, takže si s touto vlastností budete muset dělat starosti jenom v případě, že používáte checkForUpdate. (Logická hodnota)
isFirstRun: Příznak označující, jestli je aktuální spuštění aplikace první po použití balíčku. (Logická hodnota)
isMandatory: Označuje, jestli se aktualizace považuje za povinnou. Jedná se o hodnotu, která byla zadána v rozhraní příkazového řádku při vydání aktualizace. (Logická hodnota)
label: Interní popisek automaticky předaný aktualizaci serverem CodePush, například v5. Tato hodnota jednoznačně identifikuje aktualizaci v rámci jejího nasazení. (Řetězec)
packageHash: Hodnota hash SHA aktualizace. (Řetězec)
packageSize: Velikost kódu obsaženého v aktualizaci v bajtech. (Číslo)

Metody

install(installSuccess, installError, installOptions): Nainstaluje tento balíček do aplikace. Chování při instalaci závisí na zadaném installOptionsobjektu . Ve výchozím nastavení se balíček aktualizace nainstaluje bezobslužně a aplikace se znovu načte s novým obsahem při příštím spuštění aplikace. Při prvním spuštění po aktualizaci bude aplikace čekat na codePush.notifyApplicationReady() volání. Po tomto volání se operace instalace považuje za úspěšnou. V opačném případě se operace instalace označí jako neúspěšná a aplikace se při příštím spuštění vrátí na předchozí verzi.

Možnosti instalace

Rozhraní definující několik možností pro přizpůsobení chování operace instalace.

installMode: Slouží k určení parametru InstallMode použitého pro operaci instalace. Výchozí hodnota je InstallMode.ON_NEXT_RESTART.
mandatoryInstallMode: Slouží k určení parametru InstallMode použitého pro operaci instalace, pokud je balíček povinný. Výchozí hodnota je InstallMode.IMMEDIATE.
minimumBackgroundDuration: Pokud je InstallMode.ON_NEXT_RESUMEparametr installMode , slouží k určení doby, po kterou musí být aplikace na pozadí, než se při obnovení aktualizace nainstaluje. Výchozí hodnota je 0.

Příklad použití:

// App version 1 (current version)

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onInstallSuccess = function () {
    console.log("Installation succeeded.");
};

var onPackageDownloaded = function (localPackage) {
    // Install regular updates after someone navigates away from the app for more than 2 minutes
    // Install mandatory updates after someone restarts the app
    localPackage.install(onInstallSuccess, onError, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 120, mandatoryInstallMode: InstallMode.ON_NEXT_RESTART });
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        // The hash of each previously reverted package is stored for later use.
        // This way, we avoid going into an infinite bad update/revert loop.
        if (!remotePackage.failedInstall) {
            console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
            remotePackage.download(onPackageDownloaded, onError);
        } else {
            console.log("The available update was attempted before and failed.");
        }
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

//------------------------------------------------
// App version 2 (updated version)
var app = {
    onDeviceReady: function () {
        // Calling this function is required during the first application run after an update.
        // If not called, the application will be reverted to the previous version.
        window.codePush.notifyApplicationReady();
        // ...
    }
}

Příklad ochrany před chybnou aktualizací najdete v dokumentaci notifyApplicationReady().

RemotePackage

Obsahuje podrobnosti o aktualizaci, která je k dispozici ke stažení ze serveru CodePush. Odkaz na instanci tohoto objektu získáte voláním codePush.checkForUpdate metody, když je k dispozici aktualizace. Pokud používáte synchronizační rozhraní API, nemusíte si dělat starosti s RemotePackage, protože proces stažení a instalace zpracuje automaticky za vás.

Vlastnosti

Dědí RemotePackage všechny stejné vlastnosti jako LocalPackage, ale obsahuje jednu další:

downloadUrl: Adresa URL, kde je balíček k dispozici ke stažení. Tato vlastnost je potřebná pouze pro pokročilé použití, protože download metoda automaticky zpracuje získání aktualizací za vás. (Řetězec)

Metody

abortDownload(abortSuccess, abortError): Přeruší aktuální relaci stahování, pokud existuje.
download(downloadSuccess, downloadError, downloadProgress): Stáhne aktualizaci balíčku ze služby CodePush. Zpětné downloadSuccess volání je vyvoláno s argumentem LocalPackage , který představuje stažený balíček. Volitelné downloadProgress zpětné volání se během stahování vyvolá několikrát s jedním DownloadProgress parametrem.

DownloadProgress

Definuje formát objektu DownloadProgress, který se používá k odesílání pravidelných oznámení o aktualizaci o průběhu stahování aktualizace.

Vlastnosti

totalBytes: Velikost stahované aktualizace v bajtech. (Číslo)
receivedBytes: Počet již stažených bajtů. (Číslo)

Příklad použití:

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

Výčty

Rozhraní CodePush API obsahuje následující objekty výčtu, které lze použít k přizpůsobení prostředí aktualizace a jsou dostupné globálně mimo window objekt :

InstallMode

Tento výčet je určen, pokud chcete, aby se nainstalovaná aktualizace skutečně použila, a lze jej předat sync metodám nebo LocalPackage.install . Obsahuje následující hodnoty:

IMMEDIATE: Aktualizace se okamžitě použije pro spuštěnou aplikaci. Aplikace se okamžitě znovu načte s novým obsahem.
ON_NEXT_RESTART: Označuje, že chcete aktualizaci nainstalovat, ale ne vynuceně restartovat aplikaci. Když se aplikace "přirozeně" restartuje (kvůli ukončení operačního systému nebo koncovému uživateli), aktualizace se bez problémů obnoví. Tato hodnota je vhodná při provádění tichých aktualizací, protože by pravděpodobně byla pro koncového uživatele rušivá, pokud by se aplikace náhle restartovala z ničeho, protože by si ani neuvědomil, že aktualizace byla stažena. Toto je výchozí režim používaný pro metody a syncLocalPackage.install .

Příklad ochrany před chybnou aktualizací najdete v dokumentaci notifyApplicationReady().

RemotePackage

Obsahuje podrobnosti o aktualizaci, která je k dispozici ke stažení ze serveru CodePush. Odkaz na instanci tohoto objektu získáte voláním codePush.checkForUpdate metody, když je k dispozici aktualizace. Pokud používáte rozhraní API pro synchronizaci, nemusíte si s ním dělat starosti RemotePackage, protože proces stahování a instalace zpracuje automaticky za vás.

Vlastnosti

Zdědí RemotePackage všechny stejné vlastnosti jako LocalPackage, ale obsahuje ještě jednu:

downloadUrl: Adresa URL, kde je balíček k dispozici ke stažení. Tato vlastnost je potřebná pouze pro pokročilé použití, protože download metoda bude automaticky zpracovávat získávání aktualizací za vás. (Řetězec)

Metody

abortDownload(abortSuccess, abortError): Přeruší aktuální relaci stahování, pokud existuje.
download(downloadSuccess, downloadError, downloadProgress): Stáhne aktualizaci balíčku ze služby CodePush. Zpětné downloadSuccess volání je vyvoláno s argumentem LocalPackage , který představuje stažený balíček. Volitelné downloadProgress zpětné volání se vyvolá několikrát během průběhu stahování s jedním DownloadProgress parametrem.

DownloadProgress

Definuje formát objektu DownloadProgress, který se používá k odesílání pravidelných oznámení o aktualizaci o průběhu stahování aktualizací.

# Vlastnosti

totalBytes: Velikost stahované aktualizace v bajtech. (Číslo)
receivedBytes: Počet již stažených bajtů. (Číslo)

Příklad použití:

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

Výčty

Rozhraní API CodePush obsahuje následující objekty výčtu, které lze použít k přizpůsobení prostředí aktualizace a jsou globálně dostupné mimo window objekt:

InstallMode

Tento výčet je určen, pokud chcete, aby se nainstalovaná aktualizace skutečně použila, a lze jej předat sync metodám nebo LocalPackage.install . Obsahuje následující hodnoty:

IMMEDIATE: Aktualizace se okamžitě použije pro spuštěnou aplikaci. Aplikace se okamžitě znovu načte s novým obsahem.
ON_NEXT_RESTART: Označuje, že chcete aktualizaci nainstalovat, ale ne vynuceně restartovat aplikaci. Když se aplikace "přirozeně" restartuje (kvůli ukončení operačního systému nebo koncovému uživateli), aktualizace se bez problémů obnoví. Tato hodnota je vhodná při provádění tichých aktualizací, protože by pravděpodobně byla pro koncového uživatele rušivá, pokud by se aplikace náhle restartovala z ničeho, protože by si ani neuvědomil, že aktualizace byla stažena. Toto je výchozí režim používaný pro metody a syncLocalPackage.install .
ON_NEXT_RESUME: Označuje, že chcete aktualizaci nainstalovat, ale nechcete aplikaci restartovat, dokud ji koncový uživatel příště neobnoví z pozadí. Tímto způsobem nenarušíte jejich aktuální relaci, ale můžete získat aktualizaci před nimi dříve, než budete muset čekat na další přirozené restartování. Tato hodnota je vhodná pro tiché instalace, které lze použít při obnovení neinvazivním způsobem.

SyncStatus

Definuje možné stavy operace synchronizace . Existují dvě kategorie stavů: meziprodukt a výsledek (konečný). Zprostředkující stavy představují stavy průběhu operace synchronizace a nejsou konečné. Výsledné stavy představují konečné stavy operace synchronizace. Každá operace synchronizace končí pouze jedním stavem výsledku, ale může mít nulový nebo více přechodných stavů.

UP_TO_DATE: Aplikace je plně aktuální s nakonfigurovaným nasazením.
UPDATE_INSTALLED: Byla nainstalována dostupná aktualizace, která se spustí buď okamžitě po vrácení funkce zpětného volání, nebo při příštím obnovení nebo restartování aplikace v závislosti na InstallMode zadané funkci v SyncOptions.
UPDATE_IGNORED: Aplikace má volitelnou aktualizaci, kterou se koncový uživatel rozhodl ignorovat. (To platí jenom v případě, updateDialog že se používá.)
CHYBA: Během sync operace došlo k chybě. Může se jednat o chybu při komunikaci se serverem, stahování nebo rozbalování aktualizace. Protokoly konzoly by měly obsahovat další informace o tom, co se stalo. V tomto případě nebyla použita žádná aktualizace.
IN_PROGRESS: Už je spuštěná jiná synchronizace, takže tento pokus o synchronizaci byl přerušen.
CHECKING_FOR_UPDATE: Server CodePush se dotazuje na aktualizaci.
AWAITING_USER_ACTION: Je k dispozici aktualizace a koncovému uživateli se zobrazilo potvrzovací dialogové okno. (To platí jenom v případě, updateDialog že se používá.)
DOWNLOADING_PACKAGE: Ze serveru CodePush se stahuje dostupná aktualizace.
INSTALLING_UPDATE: Byla stažena dostupná aktualizace, která se chystá nainstalovat.

PhoneGap Build

Tento modul plug-in je kompatibilní s PhoneGap Build a podporuje vytváření buildů pro Android a iOS. Aby ale Mohl CodePush vypočítat hodnotu hash binárního obsahu na Androidu, phoneGap Build musí k sestavení vaší aplikace použít Gradle, což není jeho výchozí chování (používá Ant). Chcete-li tento problém vyřešit, přidejte následující prvek do souboruconfig.xml projektu jako podřízený prvek elementu <platform name="android"> :

<preference name="android-build-tool" value="gradle" />

Ukázkové aplikace

Komunita Cordova laskavě vytvořila skvělé open source aplikace, které můžou sloužit jako příklady pro vývojáře, kteří začínají. Následující seznam obsahuje aplikace OSS Cordova, které také používají CodePush, a můžete ho použít k zobrazení toho, jak službu používají ostatní uživatelé:

PGDay CodePush Demo – ukázková aplikace vytvořená Rangle.io použitá pro PhoneGap Day Europe 2016.

Poznámka

Pokud jste vyvinuli aplikaci Cordova pomocí CodePush, je to open source, dejte nám vědět. Rádi bychom ho přidali do tohoto seznamu.

Cordova Client SDK

Jak to funguje?

Podporované platformy Cordova

Začínáme

Použití modulu plug-in

Vydává se Aktualizace

Reference rozhraní API

codePush.checkForUpdate

codePush.getCurrentPackage

codePush.getPendingPackage

codePush.notifyApplicationReady

codePush.restartApplication

codePush.sync

Možnosti synchronizace

Objekty balíčků

Balíček localpackage

Vlastnosti

Metody

Možnosti instalace

RemotePackage

Vlastnosti

Metody

DownloadProgress

Vlastnosti

Výčty

InstallMode

RemotePackage

Vlastnosti

Metody

DownloadProgress

# Vlastnosti

Výčty

InstallMode

SyncStatus

PhoneGap Build

Ukázkové aplikace

Další materiály