Återanropsmeddelanden för mobilabonnemang

Artikel
03/17/2025

Överblick

När en användare har slutfört aktiveringsflödet i mobiloperatörens webbportal måste portalen ge en signal om att mobilappen vet att flödet har slutförts. Detta görs genom att utfärda ett meddelande till appen som innehåller resultatet av användarinteraktionen med webbportalen.

Transaktioner som webbportalen stöder omfattar, men är inte begränsade till, följande:

Utfärda en ny eSIM-profil (med hjälp av en aktiveringskod).
Associera enheten med en ny eller befintlig prenumeration.
Köpa en ny dataplan (antingen efterbetald eller förbetald).
Köpa ytterligare data till ett förbetalt abonnemang.
Avbryta en prenumeration.

Not

Återuppringningsmeddelandet måste returneras från värddatorn som definierats i mobiloperatörens Servicekonfiguration.

Inbyggd profilnedladdning och uppkoppling

Motringningsmetoden ska användas när du utför en eSIM-profilnedladdning i bakgrunden samtidigt som användaren hålls i mobiloperatörens webbportal. På så sätt kan portalen visa ytterligare innehåll, till exempel en kontohanteringssida, när profilnedladdningen har slutförts. Dessutom förväntas profilen göra det möjligt för enheten att registrera sig i mobilnätverket omedelbart efter aktivering, utan tidsfördröjning.

Följande diagram visar anropsflödet för en nedladdning av en inline-profil callback:

Diagram som visar nedladdningssekvensen för inlineprofil mobilabonnemang.

Det här är en reviderad version av den äldre inline-profilleverans callback-funktion, som finns för dokumentationssyfte i bilagan. Vi rekommenderar att mobiloperatörer använder den reviderade återanropsmetoden ovan.

MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData, activationCode)

Parameternamn	Typ	Beskrivning
purchaseMetadata	Objekt	Det här objektet innehåller metadata om användarens köp. Detta inkluderar information om användarkontot, köpmetoden eller instrument, information om användaren lägger till en ny rad och namnet på planen som användaren köpte. Dessa används för affärsrapportering.
aktiveringskod	Sträng	Aktiveringskoden som ska användas för att ladda ned en eSIM-profil

Returvärdetyp	Beskrivning
MobilabonnemangDriftkontext	Ett objekt med identifierare som matchar den här unika nedladdningsåtgärden.

Nedladdningen av eSIM-profilen börjar vid mottagandet av återanropsmeddelandet. Kontrollen returneras till webbportalen omedelbart efter anropet. Användargränssnittet kommer att visas som ett popup-element ovanpå webbportalen för att visa förloppet för profilnedladdning. Webbportalen kan fortsätta att navigeras under den här processen.

Följande JavaScript-funktion visar ett exempel på API:et för att informera programmet om att en profilnedladdning ska börja:

var purchaseMetaData = MobilePlans.createPurchaseMetaData();
    purchaseMetaData.userAccount = MobilePlansUserAccount.new;
    purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
    purchaseMetaData.lineType = MobilePlansLineType.new;
    purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
    purchaseMetaData.planName = "My Plan";
    MobilePlansInlineOperations.registrationChangedScript = "onRegistrationChanged";
    MobilePlansInlineOperations.profileActivationCompleteScript = "onActivationComplete";
    MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData , "1$smdp.address$matchingID");

Mer information om objektet puchaseMetadata finns i köpa metadataegenskaper.

Lyssna efter ändringar i nätverksregistreringen

Om du vill lyssna efter ändringar i nätverksregistreringen måste MobilePlansInlineProfileDownload.registrationChangedScript anges till en sträng som är namnet på en JavaScript-funktion som tar en sträng för registrationArgs.

Registrerings args är en sträng som representerar ett JSON-objekt.

ProfileRegistreringSlutfördArgument

Egenskapsnamn	Typ	Beskrivning
nätverksregistreringsstatus	Sträng	En sträng som representerar det aktuella nätverksregistreringstillståndet. Värdena för den här egenskapen kan visas i `MobilePlansNetworkRegistrationState`.
ICCID	Sträng	ICCID som nätverksregistreringstillståndet har ändrats för.

MobilPlanerNätverkRegistreringsStatus

Egenskapsnamn	Typ	Beskrivning
ingen	Sträng	Ingen anslutning.
avregistrerat	Sträng	Enheten är inte registrerad och söker inte efter en nätverksprovider.
Söker	Sträng	Enheten är inte registrerad och söker efter en nätverksprovider.
hem	Sträng	Enheten finns på en hemnätverksprovider.
roamingtjänst	Sträng	Enheten är ansluten till en roaming-nätverksleverantör.
kompanjon	Sträng	Enheten är ansluten till en nätverksleverantör för roamingpartner.
nekad	Sträng	Enheten nekades registrering.

Följande JavaScript-exempel visar hur du implementerar en lyssnare för händelser då nätverksregistreringen ändras.

function onRegistrationChanged(registrationArgs) {
    var registrationObj = JSON.parse(registrationArgs);
    if(registrationObj.networkRegistrationState == MobilePlansNetworkRegistrationState.home ||
       registrationObj.networkRegistrationState == MobilePlansNetworkRegistrationState.roaming ||
       registrationObj.networkRegistrationState == MobilePlansNetworkRegistrationState.partner)
    {
        Log('Registration Successful!');
    }
}

Lyssna efter profilaktivering

Om du vill lyssna efter profilaktiveringshändelser måste MobilePlansInlineProfileDownload.profileActivationCompleteScript anges till en sträng som är namnet på en JavaScript-funktion som accepterar en sträng för activationArgs.

activationArgs är en sträng som representerar ett JSON-objekt.

ProfileActivationCompleteArgs

Egenskapsnamn	Typ	Beskrivning
aktiveringsresultat	Sträng	Resultatet av aktiveringen. Värdena för den här egenskapen kan visas i `MobilePlansActivationError`.
iccid	Sträng	ICCID för profilen som aktiverades.

Fel vid Aktivering av Mobilabonnemang

Egenskapsnamn	Typ	Beskrivning
framgång	Sträng	Anger att en åtgärd lyckades.
inte auktoriserad	Sträng	Anger att åtgärden inte har godkänts.
inte hittad	Sträng	Anger att den angivna eSIM-profilen inte hittades.
policyöverträdelse	Sträng	Anger att åtgärden bryter mot principen.
otillräckligtUtrymmePåKortet	Sträng	Anger att det inte finns tillräckligt med lagringsutrymme på kortet för att slutföra åtgärden.
serverfel	Sträng	Anger att ett serverfel inträffade under åtgärden.
servern kan inte nås	Sträng	Anger att servern inte kunde nås under åtgärden.
timeoutVäntarPåAnvändarensSamtycke	Sträng	Anger att användarens medgivande inte beviljades inom tidsgränsen för åtgärden.
felaktigBekräftelsekod	Sträng	Anger att fel bekräftelsekod angavs under åtgärden.
Maximalt antal försök för bekräftelsekod överskridet	Sträng	Anger att fel bekräftelsekod angavs under åtgärden och att inga fler återförsök tillåts.
kortBorttaget	Sträng	Anger att SIM-kortet har tagits bort.
cardBusy	Sträng	Anger att SIM-kortet är upptaget.
annan	Sträng	Anger en status som inte täcks av en specifik status.
kortAllmäntFel	Sträng	Anger att ett kortfel inträffade som hindrade nedladdningen, installationen eller andra åtgärder från att slutföras.
bekräftelsekod saknas	Sträng	Anger att en bekräftelsekod krävs för att ladda ned eSIM-profilen.
invalidMatchingId	Sträng	Anger att matchande ID från aktiveringskoden eller den identifierade händelsen nekades.
ingenBehörigProfilFörDennaEnhet	Sträng	Anger att det inte gick att hitta en eSIM-profil som är kompatibel med den här enheten. Till exempel hittades en profil som kräver LTE-stöd, men enheten stöder bara 3G.
operation avbruten	Sträng	Anger att åtgärden avbröts.
eidMismatch	Sträng	Anger att en eSIM-profil på mobiloperatörsservern redan har allokerats för ett annat eSIM EID än den som enheten har.
profilEjTillgängligFörNyBindning	Sträng	Anger att användaren försöker ladda ned en eSIM-profil som redan har begärts eller laddats ned.
profilEjSläpptAvOperatör	Sträng	Anger att eSIM-profilen är tillgänglig, men att den ännu inte har markerats som tillgänglig för nedladdning av mobiloperatören. Endast utgivna profiler kan laddas ned, så MO måste markera profilen som frisläppt.
operationFörbjudenAvProfilklass	Sträng	Anger att åtgärden inte är tillåten för eSIM-profilklassen.
profilInteNärvarande	Sträng	Anger att det inte gick att hitta en eSIM-profil.
ingen motsvarande förfrågan	Sträng	Anger att det inte gick att hitta någon motsvarande begäran.
okänt fel	Sträng	Anger att LPA returnerade ett okänt fel.
lpaInitializationError	Sträng	Anger att ett fel uppstod vid försök att initiera LPA.
modemNotFound	Sträng	Anger att inget mobilmodem hittades på enheten.
Åtkomst till lokala inställningar misslyckades	Sträng	Anger att det inte gick att komma åt lokala inställningar för appen.
ogiltigJson	Sträng	Anger att MO-portalen har tillhandahållit ogiltig JSON när Mobilabonnemangsappen anropades.
ogiltigAktiveringskod	Sträng	Anger att MO-portalen har gett ogiltig aktiveringskod.
ogiltigICCID	Sträng	Anger att MO-portalen har gett ett ogiltigt ICCID.

I följande JavaScript-exempel visas hur du implementerar en lyssnare för profilaktiveringshändelsen.

function onActivationComplete(activationArgs) {
    var activationObj = JSON.parse(activationArgs);
    if(activationObj.activationResult == MobilePlansActivationError.success)
        Log('Activation Success');
}

Fördröjd nedladdning och aktivering av eSIM-profil

Följande diagram visar samtalsflödet för hur mobilappen stöder fördröjd nedladdning och aktivering av en eSIM-profil. Detta bör användas när eSIM-profilen inte är tillgänglig för att släppas av SM-DP+-servern och kan endast laddas ned efter en viss tidsperiod. Det förväntas att enheten kommer att kunna registrera sig i mobilnätverket när profilen har laddats ned och aktiverats.

Diagram som visar sekvensen för nedladdning av uppskjuten profil för mobila planer.

MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData, activationCode, downloadDelay)

Parameternamn	Typ	Beskrivning
purchaseMetadata	Objekt	Det här objektet innehåller metadata om användarens köp. Detta inkluderar information om användarkontot, köpmetoden eller instrument, information om användaren lägger till en ny rad och namnet på planen som användaren köpte. Alla dessa används för rapportering.
aktiveringskod	Sträng	Aktiveringskoden eller SM-DP+-adressen där profilen finns
nedladdningsfördröjning	uint	Antalet minuter att vänta innan du försöker ladda ned eSIM-profilen

Returvärdetyp	Beskrivning
MobilePlansOperationContext	Ett objekt med identifierare som matchar den här unika nedladdningsåtgärden.

Kontrollen returneras till mobiloperatörsportalen omedelbart efter anropet. Användargränssnittet visas för att informera användaren om att en profil kommer att installeras senare. När downloadDelay minuter har inträffat visas ett meddelande för användaren som uppmanar dem att påbörja nedladdningen av profilen.

Följande JavaScript-funktion visar ett exempel på API:et för att informera programmet om att en profilnedladdning med fördröjning bör påbörjas

var purchaseMetaData = MobilePlans.createPurchaseMetaData();
    purchaseMetaData.userAccount = MobilePlansUserAccount.new;
    purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
    purchaseMetaData.lineType = MobilePlansLineType.new;
    purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
    purchaseMetaData.planName = "My Plan";
    MobilePlansInlineOperations.registrationChangedScript = "onRegistrationChanged";
    MobilePlansInlineOperations.profileActivationCompleteScript = "onActivationComplete";
    MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData , "1$smdp.address$matchingID", 15);

Mer information om objektet purchaseMetadata finns i köpmetadataegenskaper.

Se lyssna efter ändringar för nätverksregistrering ovan.

Se avsnittet lyssnar efter profilaktivering ovan.

Avbryt nedladdning av eSIM-profil

Detta gäller för scenariot för uppskjuten eSIM-profilnedladdning, men det kan även användas för framtida användningsfall.

I följande diagram visas flödet på hög nivå för hur programmet Mobila planer stöder en annullering av en eSIM-profilnedladdning utan att ha kontroll över att lämna MODirect-portalen.

diagram som visar hur nedladdningssekvensen för eSIM-profilen avbryts.

MobilePlansInlineOperations.notifyOperationCancel(MobilePlansOperationContext)

Parameternamn	Typ	Beskrivning
driftkontext	Objekt	Det här objektet innehåller information som unikt identifierar en tidigare åtgärd

Den här åtgärden kan avbrytas innan användaren ser ett popup-meddelande som informerar dem om att nedladdningen är redo att påbörjas.

Följande JavaScript-funktion visar ett exempel på API:et för att avbryta en asynkron åtgärd.

var purchaseMetaData = MobilePlans.createPurchaseMetaData();
    purchaseMetaData.userAccount = MobilePlansUserAccount.new;
    purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
    purchaseMetaData.lineType = MobilePlansLineType.new;
    purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
    purchaseMetaData.planName = "My Plan";
    MobilePlansInlineOperations.registrationChangedScript = "onRegistrationChanged";
    MobilePlansInlineOperations.profileActivationCompleteScript = "onActivationComplete";
    var op = MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData , "1$smdp.address$matchingID", 15);
    MobilePlansInlineOperations.notifyOperationCancel(op);

Asynkron anslutning

Följande diagram visar flödet på hög nivå för hur mobilappen stöder fördröjd anslutning. Den här motringningsmetoden bör användas när eSIM-profilen redan är tillgänglig för lansering av SM-DP+-servern, men enheten måste vänta en stund innan den försöker registrera sig i mobilnätverket.

diagram som visar fördröjd anslutningssekvens för mobila abonnemang.

När användaren har slutfört aktiveringsflödet informerar webbportalen mobilappen om att den ska utlösa det fördröjda anslutningsflödet med hjälp av MobilePlans.notifyPurchaseWithProfileDownload-API:et.

Mobilplaner.meddelaKöpMedProfilNedladdning

Parameternamn	Typ	Beskrivning
purchaseMetadata	Objekt	Det här objektet innehåller metadata om användarens köp. Detta inkluderar information om användarkontot, köpmetoden eller instrument, information om användaren lägger till en ny rad och namnet på planen som användaren köpte. Alla dessa används för rapportering.
aktiveringskod	Sträng	Aktiveringskoden för att ladda ned eSIM-profilen. ICCID för profilen härleds från profilmetadata.
nätverksregistreringsintervall	Osignerat heltal	Den tid det tar för mobiloperatören att etablera en anslutning till användaren. Mobilappen försöker registrera sig i nätverket inom det angivna tidsintervallet, i minuter. Obs Denna tid avrundas till närmaste 15-minutersintervall. Om detta till exempel anges som 5 minuter försöker programmet registrera igen till nätverket efter cirka 15 minuter (men det kan ta längre tid). om värdet är "0" försöker enheten registrera sig omedelbart.

Följande JavaScript-funktion visar ett exempel på API:et för att informera programmet om att användarköpet kräver en fördröjd etablering av anslutningen.

function finishPurchaseWithDownload() {
       var metadata = MobilePlans.createPurchaseMetaData();
       metadata.userAccount = MobilePlansUserAccount.new;
       metadata.purchaseInstrument = MobilePlansPurchaseInstrument.new;
       metadata.moDirectStatus = MobilePlansMoDirectStatus.complete;
       metadata.line = MobilePlansLineType.new;
       metadata.planName = "2GB Monthly";
       MobilePlans.notifyPurchaseWithProfileDownload(metadata, "1$smdp.address$matchingID", 15);
}

Se köpmetadataegenskaper för mer information om purchaseMetadata-objektet.

Lägga till saldo

När en användare slutför ett köp i webbportalen genom att lägga till mer saldo i ett befintligt konto bör webbportalen anropa MobilePlansInlineOperations.notifyBalanceAddition API-returkontroll tillbaka till mobilappen. Detta kan användas för fysiska SIM- eller eSIM-profil som redan är installerade på enheten.

Följande diagram visar flödet på en hög nivå för hur Mobile Plans-appen stöder att lägga till saldo.

diagram som visar hur en mobilapp stöder att lägga till saldo.

MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData)

Parameternamn	Typ	Beskrivning
köpinformation	Objekt	Det här objektet innehåller metadata om användarens köp. Detta inkluderar information om användarkontot, köpmetoden eller instrument, information om användaren lägger till en ny rad och namnet på planen som användaren köpte. Alla dessa används för rapportering.

Returvärdetyp	Beskrivning
MobilplanerDriftKontext	Ett objekt med identifierare som matchar den här unika nedladdningsåtgärden.

När mobiloperatören vill lägga till saldo till ett visst konto bör webbportalen anropa MobilePlansInlineOperations.notifyBalanceAddition-API:et.

Följande JavaScript-funktion visar ett exempel på API:et för att informera programmet om att ett saldotillägg har gjorts.

function NotifyMobilePlans() {
    var purchaseMetaData = MobilePlans.createPurchaseMetaData();
    purchaseMetaData.userAccount = MobilePlansUserAccount.new;
    purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
    purchaseMetaData.lineType = MobilePlansLineType.new;
    purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
    purchaseMetaData.planName = "My Plan";
    MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData);
}

Mer information om puchaseMetadata-objektet finns i metadataegenskaper för inköp .

Lägga till balans och aktivera eSIM-profil

När en användare slutför ett köp i webbportalen genom att lägga till mer data i ett befintligt konto, bör webbportalen anropa MobilePlansInlineOperations.notifyBalanceAddition-API:et för att överföra kontrollen tillbaka till appen Mobilabonnemang. Detta kan användas för en eSIM-profil som redan är installerad på enheten. Parametern ICCID anger vilken eSIM-profil som ska aktiveras.

Följande diagram visar anropsflödet för hur appen Mobile Plans stödjer tillägg av saldo med iccid-information.

diagram som visar hur mobila planer lägger till balanssekvens.

MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData, iccid)

Parameternamn	Typ	Beskrivning
purchaseMetadata	Objekt	Det här objektet innehåller metadata om användarens köp. Detta inkluderar information om användarkontot, köpmetoden eller instrument, information om användaren lägger till en ny rad och namnet på planen som användaren köpte. Alla dessa används för rapportering.
iccid	Sträng	Den ICCID som ska aktiveras efter saldotillskottet

Returvärdetyp	Beskrivning
MobilePlansOperationContext	Ett objekt med identifierare som matchar den här unika nedladdningsåtgärden.

Saldotillägg kan också göras till en icke-aktiv profil om profilens ICCID är känd. Om du använder MobilePlansInlineOperations.notifyBalanceAddition med en ICCID informeras appen om saldotillägget och den aktiva profilen växlas till den profil som motsvarar den angivna ICCID:n.

Följande JavaScript-funktion visar ett exempel på API:et för att informera programmet om att ett saldotillägg har gjorts.

function NotifyMobilePlans() {
    var purchaseMetaData = MobilePlans.createPurchaseMetaData();
    purchaseMetaData.userAccount = MobilePlansUserAccount.new;
    purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
    purchaseMetaData.lineType = MobilePlansLineType.new;
    purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
    purchaseMetaData.planName = "My Plan";
    MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData, "8900000000000000001");
}

Mer information om puchaseMetadata-objektet finns i köpa metadataegenskaper.

Avbryta inköpsflödet

Om en användare avbryter aktiveringsflödet i webbportalen måste portalen anropa MobilePlans.notifyCancelledPurchase-API:et för att returnera kontrollen tillbaka till mobilappen.

MobilePlans.meddelaAvbrutenKöp

Parameternamn	Typ	Beskrivning
purchaseMetadata	Objekt	Det här objektet innehåller metadata om användarens köp. Detta inkluderar information om användarkontot, köpmetoden eller instrument, information om användaren lägger till en ny rad och namnet på planen som användaren köpte. Alla dessa används för rapportering.

Följande JavaScript-funktion visar ett exempel på API:et för att informera programmet om att användaren har avbrutit ett köp.

function finishPurchaseWithCancellation() {
       var metadata = MobilePlans.createPurchaseMetaData();
       metadata.userAccount = MobilePlansUserAccount.new;
       metadata.purchaseInstrument = MobilePlansPurchaseInstrument.new;
       metadata.moDirectStatus = MobilePlansMoDirectStatus.cancelled;
       metadata.line = MobilePlansLineType.bailed;
       metadata.planName = "";
       MobilePlans.notifyCancelledPurchase(metadata);
   }

Se köpmetadataegenskaper för detaljer om puchaseMetadata-objektet.

Information om köp av metadataegenskaper

I följande tabell beskrivs den information som används i köpmetadata.

Egenskapsnamn	Typ	Beskrivning	Exempel	Obligatoriskt/valfritt
användarkonto	Sträng	Möjliga värden: Ny: Anger att ett nytt användarkonto har skapats av användaren. Befintlig: Anger att användaren loggade in med ett befintligt användarkonto. Bailed: Anger att användaren avslutade inköpsflödet i det här steget. Ingen: Anger att användaren inte nådde det här steget.	"userAccount":"Ny"	Valfri
purchaseInstrument	Sträng	Möjliga värden: Ny: Anger att ett nytt användarkonto har skapats av användaren. Befintlig: Anger att användaren loggade in med ett befintligt användarkonto. Bailed: Anger att användaren avslutade inköpsflödet i det här steget. Ingen: Anger att användaren inte nådde det här steget.	"purchaseInstrument":"Ny"	Valfri
linje	Sträng	Möjliga värden: Ny: Anger att ett SIM-kort har lagts till av användarkontot. Befintlig: Anger att användaren överförde en befintlig rad till enheten. Bailed: Anger att användaren avslutade inköpsflödet i det här steget. Ingen: Anger att användaren inte nådde det här steget.	"line":Ny	Valfri
moDirectStatus	Sträng	Möjliga värden: Slutfört: Anger att användaren har slutfört köpet. ServiceError: Anger att användaren inte kunde slutföra köpet på grund av ett mo-tjänstfel. InvalidSIM: Anger att ICCID som skickades till portalen var felaktigt. LogOnFailed: anger att användaren inte kunde logga in på MO-portalen. PurchaseFailed: Anger att köpet misslyckades på grund av ett faktureringsfel. ClientError: Anger att ogiltiga argument skickades till portalen. BillingError: Anger att det uppstod ett fel med användarfakturering.	"moDirectStatus":"Slutförd"	Krävs
plansnamn	Sträng	För en lyckad transaktion får det här fältet inte vara tomt och måste ange ett beskrivande plannamn. För en misslyckad transaktion måste det här fältet vara en tom sträng.	"planName":"2GB per månad"	Sträng som inte är tom krävs

Information om MobilePlansOperationContext

I följande tabell beskrivs egenskaperna för MobilePlansOperationContext

Egenskapsnamn	Typ	Beskrivning
Id	sträng	unikt ID som skapats av appen för en åtgärd

Äldre återanropsmeddelanden

Se den specifika sidan där alla äldre återanrop dokumenteras.

Dela via