Creare un’app smart card NFCCreate an NFC Smart Card app

Importante

Questo argomento si applica solo a Windows 10 Mobile.This topic applies to Windows 10 Mobile only.

Per supportare le app di emulazione di carte NFC, Windows Phone 8.1 richiede l'accoppiamento stretto tra app per il pagamento sicuro e operatori di rete mobile.Windows Phone 8.1 supported NFC card emulation apps using a SIM-based secure element, but that model required secure payment apps to be tightly coupled with mobile-network operators (MNO). Questo aspetto ha limitato la scelta di possibili soluzioni di pagamento fornite da altri rivenditori o sviluppatori non accoppiate a operatori di rete mobile.This limited the variety of possible payment solutions by other merchants or developers that are not coupled with MNOs. In Windows 10 Mobile abbiamo introdotto una nuova tecnologia di emulazione delle carte magnetiche denominata HCE (Host Card Emulation).In Windows 10 Mobile, we have introduced a new card emulation technology called, Host Card Emulation (HCE). La tecnologia HCE consente all'app di comunicare direttamente con un lettore di carte magnetiche NFC.HCE technology allows your app to directly communicate with an NFC card reader. Questo argomento illustra il funzionamento di HCE (Host Card Emulation) nei dispositivi Windows 10 Mobile e ti spiega come sviluppare un'app HCE in modo che i clienti possano accedere ai tuoi servizi tramite telefono, anziché tramite una carta fisica, senza dover collaborare con un operatore di rete mobile.This topic illustrates how Host Card Emulation (HCE) works on Windows 10 Mobile devices and how you can develop an HCE app so that your customers can access your services through their phone instead of a physical card without collaborating with an MNO.

Cosa serve per sviluppare un'app HCEWhat you need to develop an HCE app

Per sviluppare un'app di emulazione di carte magnetiche basata su HCE per Windows 10 Mobile, ti servirà configurare l'ambiente di sviluppo.To develop an HCE-based card emulation app for Windows 10 Mobile, you will need to get your development environment setup. Per preparare la configurazione puoi installare Microsoft Visual Studio 2015, che include gli strumenti di sviluppo di Windows e l'emulatore di Windows 10 Mobile con il supporto dell'emulazione NFC.You can get set up by installing Microsoft Visual Studio 2015, which includes the Windows developer tools and the Windows 10 Mobile emulator with NFC emulation support. Per altre informazioni su questi preparativi, vedi Effettua la configurazioneFor more information about getting setup, see, Get set up

Facoltativamente, se vuoi eseguire i test con un dispositivo Windows 10 Mobile reale invece dell'emulatore di Windows 10 Mobile incluso, ti serviranno anche gli elementi seguenti.Optionally, if you want to test with a real Windows 10 Mobile device instead of the included Windows 10 Mobile emulator, you will also need the following items.

  • Un dispositivo Windows 10 Mobile con supporto di HCE NFC.A Windows 10 Mobile device with NFC HCE support. L'hardware per il supporto delle app HCE NFC è attualmente disponibile nei Lumia 730, 830, 640 e 640 XL.Currently, the Lumia 730, 830, 640, and the 640 XL have the hardware to support NFC HCE apps.
  • Un terminale lettore che supporta i protocolli ISO/IEC 14443-4 e ISO/IEC 7816-4A reader terminal that supports protocols ISO/IEC 14443-4 and ISO/IEC 7816-4

Windows 10 Mobile implementa un servizio HCE che fornisce le seguenti funzionalità.Windows 10 Mobile implements an HCE service that provides the following functionalities.

  • Le app possono registrare gli identificatori di applet (AID, Applet Identifier) per le carte da emulare.Apps can register the applet identifiers (AIDs) for the cards they would like to emulate.
  • Risoluzione dei conflitti e routing delle coppie di comandi e risposte APDU (Application Protocol Data Unit) a una delle app registrate in base alla selezione della carta del lettore esterno e alle preferenze dell'utente.Conflict resolution and routing of the Application Protocol Data Unit (APDU) command and response pairs to one of the registered apps based on the external reader card selection and user preference.
  • Gestione di eventi e notifiche per le app in risposta alle azioni dell'utente.Handling of events and notifications to the apps as a result of user actions.

Windows 10 supporta l'emulazione di smart card basate su ISO-DEP (ISO-IEC 14443-4) e comunica tramite APDU, come definito nella specifica ISO-IEC 7816-4.Windows 10 supports emulation of smart cards that are based on ISO-DEP (ISO-IEC 14443-4) and communicates using APDUs as defined in the ISO-IEC 7816-4 specification. Windows 10 supporta la tecnologia ISO/IEC 14443-4 di tipo A per le app HCE.Windows 10 supports ISO/IEC 14443-4 Type A technology for HCE apps. Le tecnologie di tipo B, di tipo F e non ISO-DEP (ad esempio MIFARE) vengono indirizzate alla SIM per impostazione predefinita.Type B, type F, and non-ISO-DEP (eg MIFARE) technologies are routed to the SIM by default.

La funzionalità di emulazione delle carte magnetiche è abilitata solo nei dispositivi Windows 10 Mobile.Only Windows 10 Mobile devices are enabled with the card emulation feature. L'emulazione delle carte basate su SIM e HCE non è disponibile in altre versioni di Windows 10.SIM-based and HCE-based card emulation is not available on other versions of Windows 10.

L'architettura per il supporto dell'emulazione delle carte basate su SIM e HCE è illustrata nel diagramma seguente.The architecture for HCE and SIM based card emulation support is shown in the diagram below.

Architettura per l'emulazione delle carte basate su SIM e HCE

Selezione dell'app e routing degli AIDApp selection and AID routing

Per sviluppare un'app HCE, devi capire come i dispositivi Windows 10 Mobile indirizzano gli AID a un'app specifica perché gli utenti possano installare più app HCE diverse.To develop an HCE app, you must understand how Windows 10 Mobile devices route AIDs to a specific app because users can install multiple different HCE apps. Ogni app può registrare più carte basate su HCE e SIM.Each app can register multiple HCE and SIM-based cards. Le app di Windows Phone 8.1 legacy basate su SIM continueranno a funzionare in Windows 10 Mobile, a condizione che l'utente scelga l'opzione "Scheda SIM" come carta di pagamento predefinita nel menu delle impostazioni NFC.Legacy Windows Phone 8.1 apps that are SIM-based will continue to work on Windows 10 Mobile as long as the user chooses the "SIM Card" option as their default payment card in the NFC Setting menu. Questa opzione viene configurata per impostazione predefinita alla prima accensione del dispositivo.This is set by default when turning the device on for the first time.

Quando l'utente tocca un terminale con il dispositivo Windows 10 Mobile, i dati vengono indirizzati automaticamente all'app corretta installata nel dispositivo.When the user taps their Windows 10 Mobile device to a terminal, the data is automatically routed to the proper app installed on the device. Il routing è basato sugli ID dell'applet (AID), ovvero identificatori da 5-16 byte.This routing is based on the applet IDs (AIDs) which are 5-16 byte identifiers. Durante un tocco, il terminale esterno trasmetterà un'unità APDU con comando SELECT per specificare l'AID a cui vorrebbe indirizzare tutti i comandi APDU successivi.During a tap, the external terminal will transmit a SELECT command APDU to specify the AID it would like all subsequent APDU commands to be routed to. I comandi SELECT successivi modificheranno nuovamente il routing.Subsequent SELECT commands, will change the routing again. Sulla base degli AID registrati dalle app e dalle impostazioni utente, il traffico APDU viene indirizzato a un'app specifica, che invierà un'unità APDU di risposta.Based on the AIDs registered by apps and user settings, the APDU traffic is routed to a specific app, which will send a response APDU. Tieni presente che un terminale potrebbe voler comunicare con varie app diverse durante lo stesso tocco.Be aware that a terminal may want to communicate with several different apps during the same tap. Devi quindi assicurarti che l'attività in background della tua app esca il prima possibile dopo la disattivazione, per consentire all'attività in background di un'altra app di rispondere all'APDU.So you must ensure your app's background task exits as quickly as possible when deactivated to make room for another app's background task to respond to the APDU. Parleremo in maggiore dettaglio delle attività in background più avanti in questo argomento.We will discuss background tasks later in this topic.

Le app HCE devono registrarsi per gli AID specifici che possono gestire in modo da ricevere le unità APDU per un AID.HCE apps must register themselves with particular AIDs they can handle so they will receive APDUs for an AID. Le app dichiarano gli AID tramite gruppi di AID.Apps decalre AIDs by using AID groups. Un gruppo di AID è concettualmente equivalente a una singola carta fisica.An AID group is conceptually equivalent to an individual physical card. Ad esempio, una carta di credito viene dichiarata con un gruppo di AID e una seconda carta di credito di una banca diversa viene dichiarata con un secondo gruppo di AID diverso, anche se entrambe potrebbero avere lo stesso AID.For example, one credit card is declared with an AID group and a second credit card from a different bank is declared with a different, second AID group, even though both of them may have the same AID.

Risoluzione dei conflitti per i gruppi di AID di pagamentoConflict resolution for payment AID groups

Quando un'app registra carte fisiche (gruppi di AID), può dichiarare la categoria del gruppo di AID come "Payment" o "Other".When an app registers physical cards (AID groups), it can declare the AID group category as either "Payment" or "Other." Anche se in un determinato momento possono essere registrati più gruppi di AID di pagamento, solo uno alla volta può essere abilitato per la funzionalità Tocca per pagare e viene selezionato dall'utente.While there can be multiple payment AID groups registered at any given time, only one of these payment AID groups may be enabled for Tap and Pay at a time, which is selected by the user. Questo comportamento è dovuto al fatto che l'utente si aspetta di avere il controllo della scelta di una singola carta di pagamento, di credito o di debito da usare, in modo da evitare di usare una carta diversa non prevista per il pagamento quando tocca un terminale con il dispositivo.This behavior exists because the user expects be in control of consciously choosing a single payment, credit, or debit card to use so they don't pay with a different unintended card when tapping their device to a terminal.

Tuttavia, più gruppi di AID registrati come "Other" possono essere abilitati allo stesso tempo senza interazione dell'utente.However, multiple AID groups registered as "Other" can be enabled at the same time without user interaction. Questo comportamento esiste perché è previsto che altri tipi di carte, come carte fedeltà, coupon o carte di transito, funzionino senza problemi o senza ulteriori richieste quando gli utenti toccano il telefono.This behavior exists because other types of cards like loyalty, coupons, or transit are expected to just work without any effort or prompting whenever they tap their phone.

Tutti i gruppi di AID registrati come "Payment" vengono visualizzati nell'elenco delle carte nella pagina Impostazioni NFC, in cui l'utente può selezionare la carta di pagamento predefinita.All the AID groups that are registered as "Payment" appear in the list of cards in the NFC Settings page, where the user can select their default payment card. Quando viene selezionata una carta di pagamento predefinita, l'app che ha registrato questo gruppo di AID di pagamento diventa l'app di pagamento predefinita.When a default payment card is selected, the app that registered this payment AID group becomes the default payment app. Le app di pagamento predefinite possono abilitare o disabilitare uno qualsiasi dei gruppi di AID senza interazione dell'utente.Default payment apps can enable or disable any of their AID groups without user interaction. Se l'utente non acconsente alla richiesta di conferma dell'app di pagamento predefinita, continuerà a rimanere impostata come predefinita l'eventuale app di pagamento predefinita corrente.If the user declines the default payment app prompt, then the current default payment app (if any) continues to remain as default. Lo screenshot seguente mostra la pagina Impostazioni NFC.The following screenshot shows the NFC Settings page.

Screenshot della pagina Impostazioni NFC.

Facendo riferimento allo screenshot di esempio precedente, se l'utente sostituisce la carta di pagamento predefinita con un'altra carta non registrata da "Applicazione HCE 1", il sistema crea un messaggio di conferma per richiedere il consenso dell'utente.Using the example screenshot above, if the user changes his default payment card to another card that is not registered by "HCE Application 1," the system creates a confirmation prompt for the user’s consent. Se invece l'utente sostituisce la sua carta di pagamento predefinita con un'altra carta registrata da "Applicazione HCE 1", il sistema non crea un messaggio di conferma per l'utente, perché "Applicazione HCE 1" è già l'app di pagamento predefinita.However, if the user changes his default payment card to another card that is registered by "HCE Application 1," the system does not create a confirmation prompt for the user, because "HCE Application1" is already the default payment app.

Risoluzione dei conflitti per i gruppi di AID non di pagamentoConflict resolution for non-payment AID groups

Le carte non di pagamento categorizzate come "Other" non vengono visualizzate nella pagina Impostazioni NFC.Non-payment cards categorized as "Other" do not appear in the NFC settings page.

L'app può creare, registrare e abilitare gruppi di AID non di pagamento nello stesso modo dei gruppi di pagamento.Your app can create, register and enable non-payment AID groups in the same manner as payment AID groups. La differenza principale è che per i gruppi di AID non di pagamento la categoria di emulazione è impostata su "Other" anziché "Payment".The main difference is that for non-payment AID groups the emulation category is set to "Other" as opposed to "Payment". Dopo la registrazione del gruppo di AID nel sistema, dovrai abilitare il gruppo per la ricezione del traffico NFC.After registering the AID group with the system, you need to enable the AID group to receive NFC traffic. Quando tenti di abilitare un gruppo di AID non di pagamento per la ricezione del traffico, non viene visualizzata una richiesta di conferma all'utente a meno che non esista un conflitto con uno degli AID già registrati nel sistema da un'altra app.When you try to enable a non-payment AID group to receive traffic, the user is not prompted for a confirmation unless there is a conflict with one of the AIDs already registered in the system by a different app. In presenza di un conflitto, verranno visualizzate informazioni all'utente con indicazione di quale carta e quale app associata verranno disabilitate se l'utente sceglie di abilitare il gruppo di AID appena registrato.If there is a conflict, the user will be prompted with information about which card and it's associated app will be disabled if the user chooses to enable the newly registered AID group.

Coesistenza con le applicazioni NFC basate su SIMCoexistence with SIM based NFC applications

In Windows 10 Mobile il sistema configura la tabella di routing del controller NFC usata per prendere decisioni di routing al livello del controller.In Windows 10 Mobile, the system sets up the NFC controller routing table that is used to make routing decisions at the controller layer. La tabella contiene informazioni di routing per gli elementi seguenti:The table contains routing information for the following items.

  • Singole route AID.Individual AID routes.
  • Route basata su protocollo (ISO-DEP).Protocol based route (ISO-DEP).
  • Routing basato sulla tecnologia (NFC-A/B/F).Technology based routing (NFC-A/B/F).

Quando un lettore esterno invia un comando "SELECT AID", il controller NFC controlla prima di tutto se esiste una corrispondenza nella tabella di routing per le route AID.When an external reader sends a "SELECT AID" command, the NFC controller first checks AID routes in the routing table for a match. In assenza di corrispondenze, userà la route basata su protocollo come route predefinita per il traffico ISO-DEP (14443-4-A).If there is no match, it will use the protocol-based route as the default route for ISO-DEP (14443-4-A) traffic. Per qualsiasi altro traffico non ISO-DEP verrà usato il routing basato sulla tecnologia.For any other non-ISO-DEP traffic it will use the technology based routing.

Windows 10 Mobile offre un'opzione di menu "Scheda SIM" nella pagina Impostazioni NFC per continuare a usare le app basate su SIM di Windows Phone 8.1 legacy, che non registrano i rispettivi AID nel sistema.Windows 10 Mobile provides a menu option "SIM Card" in the NFC Settings page to continue to use legacy Windows Phone 8.1 SIM-based apps, which do not register their AIDs with the system. Se l'utente seleziona "Scheda SIM" come carta di pagamento predefinita, la route ISO-DEP viene impostata su UICC e per tutte le altre selezioni nel menu a discesa la route ISO-DEP è verso l'host.If the user selects "SIM card" as their default payment card, then the ISO-DEP route is set to UICC, for all other selections in the drop-down menu the ISO-DEP route is to the host.

La route ISO-DEP viene impostata su "Scheda SIM" per i dispositivi con una scheda SIM abilitata per SE al primo avvio del dispositivo Windows 10 Mobile.The ISO-DEP route is set to "SIM Card" for devices that have an SE enabled SIM card when the device is booted for the first time with Windows 10 Mobile. Quando l'utente installa un'app abilitata per HCE e l'app abilita eventuali registrazioni di gruppi di AID HCE, la route ISO-DEP punterà all'host.When the user installs an HCE enabled app and that app enables any HCE AID group registrations, the ISO-DEP route will be pointed to the host. Le nuove applicazioni basate su SIM devono registrare i rispettivi AID nella SIM in modo da popolare le route AID specifiche nella tabella di routing del controller.New SIM-based applications need to register the AIDs in the SIM in order for the specific AID routes to be populated in the controller routing table.

Creazione di un'app basata su HCECreating an HCE based app

L'app HCE è composta da due parti.Your HCE app has two parts.

  • L'app in primo piano principale per l'interazione con l'utente.The main foreground app for the user interaction.
  • Un'attività in background che viene generata dal sistema per elaborare le unità APDU per un determinato AID.A background task that is triggered by the system to process APDUs for a given AID.

A causa dei requisiti di prestazioni molto alti per il caricamento dell'attività in background in risposta a un tocco NFC, consigliamo di implementare l'intera attività in background in codice nativo C++ /CX (inclusi eventuali riferimenti, dipendenze o raccolte da cui dipendi), anziché in codice C# o codice gestito.Because of the extremely tight performance requirements for loading your background task in response to an NFC tap, we recommend that your entire background task be implementing in C++/CX native code (including any dependencies, references, or libraries you depend on) rather than C# or managed code. Sebbene il codice C# e gestito offra normalmente buone prestazioni, è presente overhead come il caricamento del CLR .NET, che può essere evitato scrivendolo in C++/CX.While C# and managed code normally performs well, there is overhead, like loading the .NET CLR, that can be avoided by writing it in C++/CX.

Creare e registrare l'attività in backgroundCreate and register your background task

Devi creare un'attività in background nella tua app HCE per elaborare e rispondere alle unità APDU indirizzate all'app dal sistema.You need to create a background task in your HCE app for processing and responding to APDUs routed to it by the system. Durante la prima avvio dell'app, il primo piano registra un'attività in background HCE che implementa l'interfaccia IBackgroundTaskRegistration , come illustrato nel codice seguente.During the first time your app is launched, the foreground registers an HCE background task that implements the IBackgroundTaskRegistration interface as shown in the following code.

var taskBuilder = new BackgroundTaskBuilder();
taskBuilder.Name = bgTaskName;
taskBuilder.TaskEntryPoint = taskEntryPoint;
taskBuilder.SetTrigger(new SmartCardTrigger(SmartCardTriggerType.EmulatorHostApplicationActivated));
bgTask = taskBuilder.Register();

Si noti che il trigger attività è impostato su SmartCardTriggerType.Notice that the task trigger is set to SmartCardTriggerType. EmulatorHostApplicationActivated.EmulatorHostApplicationActivated. Questo significa che ogni volta che il sistema operativo riceve un'unità APDU con comando SELECT AID corrispondente alla tua app, verrà avviata la tua attività in background.This means that whenever a SELECT AID command APDU is received by the OS resolving to your app, your background task will be launched.

Ricevere e rispondere alle unità APDUReceive and respond to APDUs

In presenza di un'unità APDU indirizzata alla tua app, il sistema avvierà la tua attività in background.When there is an APDU targeted for your app, the system will launch your background task. L'attività in background riceve la APDU passata attraverso la proprietà CommandApdu dell'oggetto SmartCardEmulatorApduReceivedEventArgs e risponde a APDU usando il metodo TryRespondAsync dello stesso oggetto.Your background task receives the APDU passed through the SmartCardEmulatorApduReceivedEventArgs object’s CommandApdu property and responds to the APDU using the TryRespondAsync method of the same object. Valuta la possibilità di destinare l'attività in background a operazioni leggere per motivi di prestazioni.Consider keeping your background task for light operations for performance reasons. Ad esempio, rispondi immediatamente alle unità APDU ed esci dall'attività in background non appena viene completata tutta l'elaborazione.For example, respond to the APDUs immediately and exit your background task when all processing is complete. A causa della natura delle transazioni NFC, gli utenti tendono a mantenere il dispositivo sul lettore solo per un periodo di tempo molto breve.Due to the nature of NFC transactions, users tend to hold their device against the reader for only a very short amount of time. L’attività in background continuerà a ricevere il traffico dal lettore fino alla disattivazione della connessione, quando riceverai un oggetto SmartCardEmulatorConnectionDeactivatedEventArgs.Your background task will continue to receive traffic from the reader until your connection is deactivated, in which case you will receive a SmartCardEmulatorConnectionDeactivatedEventArgs object. La connessione può essere disattivata per i motivi seguenti, come indicato nella proprietà SmartCardEmulatorConnectionDeactivatedEventArgs. Reason .Your connection can be deactivated because of the following reasons as indicated in the SmartCardEmulatorConnectionDeactivatedEventArgs.Reason property.

  • Se la connessione viene disattivata con il valore ConnectionLost, significa che l’utente ha allontanato il dispositivo dal lettore.If the connection is deactivated with the ConnectionLost value, it means that the user pulled their device away from the reader. Se l'app ha bisogno che l'utente tocchi il terminale per un periodo più lungo, puoi valutare la possibilità di avvisarlo con una qualche forma di feedback.If your app needs the user to tap to the terminal longer, you might want to consider prompting them with feedback. Dovresti terminare l'attività in background rapidamente (completando il differimento) per assicurarti che in caso di ulteriore tocco non si verifichino ritardi in attesa dell'uscita dell'attività in background precedente.You should terminate your background task quickly (by completing your deferral) to ensure if they tap again it won’t be delayed waiting for the previous background task to exit.
  • Se la connessione viene disattivata con ConnectionRedirected, significa che il terminale ha inviato una nuova unità ADPU con comando SELECT AID indirizzata a un AID diverso.If the connection is deactivated with the ConnectionRedirected, it means that the terminal sent a new SELECT AID command APDU directed to a different AID. In questo caso, l'app dovrebbe uscire dall'attività in background immediatamente (completando il differimento) per consentire l'esecuzione di un'altra attività in background.In this case, your app should exit the background task immediately (by completing your deferral) to allow another background task to run.

L’attività in background dovrebbe registrarsi anche per l’evento Canceled event su IBackgroundTaskInstance interface e uscire velocemente (completando il differimento), perché questo evento viene generato dal sistema quando ha finito di elaborare l’attività in background.The background task should also register for the Canceled event on IBackgroundTaskInstance interface, and likewise quickly exit the background task (by completing your deferral) because this event is fired by the system when it is finished with your background task. Il codice seguente illustra un'attività in background per l'app HCE.Below is code that demonstrates an HCE app background task.

void BgTask::Run(
    IBackgroundTaskInstance^ taskInstance)
{
    m_triggerDetails = static_cast<SmartCardTriggerDetails^>(taskInstance->TriggerDetails);
    if (m_triggerDetails == nullptr)
    {
        // May be not a smart card event that triggered us
        return;
    }

    m_emulator = m_triggerDetails->Emulator;
    m_taskInstance = taskInstance;

    switch (m_triggerDetails->TriggerType)
    {
    case SmartCardTriggerType::EmulatorHostApplicationActivated:
        HandleHceActivation();
        break;

    case SmartCardTriggerType::EmulatorAppletIdGroupRegistrationChanged:
        HandleRegistrationChange();
        break;

    default:
        break;
    }
}

void BgTask::HandleHceActivation()
{
 try
 {
        auto lock = m_srwLock.LockShared();
        // Take a deferral to keep this background task alive even after this "Run" method returns
        // You must complete this deferal immediately after you have done processing the current transaction
        m_deferral = m_taskInstance->GetDeferral();

        DebugLog(L"*** HCE Activation Background Task Started ***");

        // Set up a handler for if the background task is cancelled, we must immediately complete our deferral
        m_taskInstance->Canceled += ref new Windows::ApplicationModel::Background::BackgroundTaskCanceledEventHandler(
            [this](
            IBackgroundTaskInstance^ sender,
            BackgroundTaskCancellationReason reason)
        {
            DebugLog(L"Cancelled");
            DebugLog(reason.ToString()->Data());
            EndTask();
        });

        if (Windows::Phone::System::SystemProtection::ScreenLocked)
        {
            auto denyIfLocked = Windows::Storage::ApplicationData::Current->RoamingSettings->Values->Lookup("DenyIfPhoneLocked");
            if (denyIfLocked != nullptr && (bool)denyIfLocked == true)
            {
                // The phone is locked, and our current user setting is to deny transactions while locked so let the user know
                // Denied
                DoLaunch(Denied, L"Phone was locked at the time of tap");

                // We still need to respond to APDUs in a timely manner, even though we will just return failure
                m_fDenyTransactions = true;
            }
        }
        else
        {
            m_fDenyTransactions = false;
        }

        m_emulator->ApduReceived += ref new TypedEventHandler<SmartCardEmulator^, SmartCardEmulatorApduReceivedEventArgs^>(
            this, &BgTask::ApduReceived);

        m_emulator->ConnectionDeactivated += ref new TypedEventHandler<SmartCardEmulator^, SmartCardEmulatorConnectionDeactivatedEventArgs^>(
                [this](
                SmartCardEmulator^ emulator,
                SmartCardEmulatorConnectionDeactivatedEventArgs^ eventArgs)
            {
                DebugLog(L"Connection deactivated");
                EndTask();
            });

  m_emulator->Start();
        DebugLog(L"Emulator started");
 }
 catch (Exception^ e)
 {
        DebugLog(("Exception in Run: " + e->ToString())->Data());
        EndTask();
 }
}

Creare e registrare gruppi di AIDCreate and register AID groups

Durante il primo avvio dell'applicazione quando avviene il provisioning della carta, dovrai creare i gruppi di AID e registrarli nel sistema.During the first launch of your application when the card is being provisioned, you will create and register AID groups with the system. Il sistema determina l'app con cui potrebbe voler comunicare un lettore esterno e indirizza le unità APDU corrispondentemente, in base agli AID registrati e alle impostazioni utente.The system determines the app that an external reader would like to talk to and route APDUs accordingly based on the registered AIDs and user settings.

La maggior parte delle carte di pagamento viene registrata con lo stesso AID (AID PPSE) insieme a ulteriori AID specifici della carta della rete di pagamento.Most of the payment cards register for the same AID (which is PPSE AID) along with additional payment network card specific AIDs. Ogni gruppo di AID rappresenta una carta e quando l'utente abilita la carta vengono abilitati tutti gli AID nel gruppo.Each AID group represents a card and when the user enables the card, all AIDs in the group are enabled. In modo analogo, quando l'utente disattiva la carta, vengono disabilitati tutti gli AID nel gruppo.Similarly, when the user deactivates the card, all AIDs in the group are disabled.

Per registrare un gruppo di AID, devi creare un oggetto SmartCardAppletIdGroup e impostarne le proprietà in modo che indichino che si tratta di una carta di pagamento basata su HCE.To register an AID group, you need to create a SmartCardAppletIdGroup object and set its properties to reflect that this is an HCE-based payment card. Il tuo nome visualizzato dovrebbe essere descrittivo per l'utente perché comparirà nel menu delle impostazioni NFC e nelle richieste per l'utente.Your display name should be descriptive to the user because it will show up in the NFC settings menu as well as user prompts. Per le carte di pagamento HCE, la proprietà SmartCardEmulationCategory dovrebbe essere impostata su Payment e la proprietà SmartCardEmulationType dovrebbe essere impostata su Host.For HCE payment cards, the SmartCardEmulationCategory property should be set to Payment and the SmartCardEmulationType property should be set to Host.

public static byte[] AID_PPSE =
        {
            // File name "2PAY.SYS.DDF01" (14 bytes)
            (byte)'2', (byte)'P', (byte)'A', (byte)'Y',
            (byte)'.', (byte)'S', (byte)'Y', (byte)'S',
            (byte)'.', (byte)'D', (byte)'D', (byte)'F', (byte)'0', (byte)'1'
        };

var appletIdGroup = new SmartCardAppletIdGroup(
                        "Example DisplayName",
                                new List<IBuffer> {AID_PPSE.AsBuffer()},
                                SmartCardEmulationCategory.Payment,
                                SmartCardEmulationType.Host);

Per le carte HCE non di pagamento, la proprietà SmartCardEmulationCategory dovrebbe essere impostata su Other e la proprietà SmartCardEmulationType dovrebbe essere impostata su Host.For non-payment HCE cards, the SmartCardEmulationCategory property should be set to Other and the SmartCardEmulationType property should be set to Host.

public static byte[] AID_OTHER =
        {
            (byte)'1', (byte)'2', (byte)'3', (byte)'4',
            (byte)'5', (byte)'6', (byte)'7', (byte)'8',
            (byte)'O', (byte)'T', (byte)'H', (byte)'E', (byte)'R'
        };

var appletIdGroup = new SmartCardAppletIdGroup(
                        "Example DisplayName",
                                new List<IBuffer> {AID_OTHER.AsBuffer()},
                                SmartCardEmulationCategory.Other,
                                SmartCardEmulationType.Host);

Puoi includere fino a 9 AID (ognuno con lunghezza di 5-16 byte) in ogni gruppo di AID.You can include up to 9 AIDs (of length 5-16 bytes each) per AID group.

Usare il metodo RegisterAppletIdGroupAsync per registrare il gruppo di aiuti con il sistema, che restituirà un oggetto SmartCardAppletIdGroupRegistration .Use the RegisterAppletIdGroupAsync method to register your AID group with the system, which will return a SmartCardAppletIdGroupRegistration object. Per impostazione predefinita, la proprietà ActivationPolicy dell’oggetto di registrazione è impostata su Disabled.By default, the ActivationPolicy property of the registration object is set to Disabled. Questo significa che anche se gli AID sono registrati nel sistema, non sono ancora abilitati e non riceveranno il traffico.This means even though your AIDs are registered with the system, they are not enabled yet and won’t receive traffic.

reg = await SmartCardEmulator.RegisterAppletIdGroupAsync(appletIdGroup);

Puoi abilitare le carte registrate (gruppi di AID) tramite il metodo RequestActivationPolicyChangeAsync della classe SmartCardAppletIdGroupRegistration, come mostrato di seguito.You can enable your registered cards (AID groups) by using the RequestActivationPolicyChangeAsync method of theSmartCardAppletIdGroupRegistration class as shown below. Dato che è possibile abilitare una sola carta di pagamento alla volta nel sistema, l’impostazione di ActivationPolicy per un gruppo di AID di pagamento su Enabled corrisponde all’impostazione della carta di pagamento predefinita.Because only a single payment card can be enabled at a time on the system, setting the ActivationPolicy of a payment AID group to Enabled is the same as setting the default payment card. All'utente verrà richiesto di acconsentire all'uso della carta come carta di pagamento predefinita, indipendentemente dal fatto che ci sia già una carta di pagamento predefinita selezionata o meno.The user will be prompted to allow this card as a default payment card, regardless of whether there is a default payment card already selected or not. Questa affermazione non è vera se la tua app è già l'applicazione di pagamento predefinita e sta semplicemente cambiando i suoi gruppi di AID.This statement is not true if your app is already the default payment application, and is merely changing between it’s own AID groups. Puoi registrare fino a 10 gruppi di AID per ogni app.You can register up to 10 AID groups per app.

reg.RequestActivationPolicyChangeAsync(AppletIdGroupActivationPolicy.Enabled);

È possibile eseguire una query sui gruppi di aiuti registrati dell'app con il sistema operativo e verificare i criteri di attivazione usando il metodo GetAppletIdGroupRegistrationsAsync .You can query your app’s registered AID groups with the OS and check their activation policy using the GetAppletIdGroupRegistrationsAsync method.

Agli utenti verrà segnalata la modifica dei criteri di attivazione di una carta di pagamento da Disabled a Enabled, solo se la tua app non è già l’app di pagamento predefinita.Users will be prompted when you change the activation policy of a payment card from Disabled to Enabled, only if your app is not already the default payment app. Agli utenti verrà segnalata la modifica dei criteri di attivazione di una carta non di pagamento da Disabled a Enabled, solo in presenza di un conflitto di AID.Users will only be prompted when you change the activation policy of a non-payment card from Disabled to Enabled if there is an AID conflict.

var registrations = await SmartCardEmulator.GetAppletIdGroupRegistrationsAsync();
    foreach (var registration in registrations)
    {
registration.RequestActivationPolicyChangeAsync (AppletIdGroupActivationPolicy.Enabled);
    }

Notifica di eventi al variare dei criteri di attivazioneEvent notification when activation policy change

Nella tua attività in background puoi effettuare la registrazione per ricevere gli eventi in caso di modifica dei criteri di attivazione delle tue registrazioni di gruppi di AID al di fuori della tua app.In your background task, you can register to receive events for when the activation policy of one of your AID group registrations changes outside of your app. Ad esempio, l'utente potrebbe modificare l'app di pagamento predefinita tramite il menu delle impostazioni NFC, sostituendo una delle tue carte con un'altra carta ospitata da un'altra app.For example, the user may change the default payment app through the NFC settings menu from one of your cards to another card hosted by another app. Se l'app deve essere informata di questa modifica per operazioni di configurazione interna, come l'aggiornamento dei riquadri animati, puoi ricevere notifiche di eventi per questa modifica e agire nella tua app di conseguenza.If your app needs to know about this change for internal setup such as updating live tiles, you can receive event notifications for this change and take action in your app accordingly.

var taskBuilder = new BackgroundTaskBuilder();
taskBuilder.Name = bgTaskName;
taskBuilder.TaskEntryPoint = taskEntryPoint;
taskBuilder.SetTrigger(new SmartCardTrigger(SmartCardTriggerType.EmulatorAppletIdGroupRegistrationChanged));
bgTask = taskBuilder.Register();

Comportamento di override per l'app in primo pianoForeground override behavior

Puoi modificare la proprietà ActivationPolicy di qualsiasi registrazione di gruppi di AID impostandola su ForegroundOverride mentre l’app è in primo piano senza chiedere conferma all’utente.You can change the ActivationPolicy of any of your AID group registrations to ForegroundOverride while your app is in the foreground without prompting the user. Quando l'utente tocca un terminale con il dispositivo mentre la tua app è in primo piano, il traffico viene indirizzato all'app anche se nessuna delle tue carte di pagamento è stata scelta dall'utente come carta di pagamento predefinita.When the user taps their device to a terminal while your app is in the foreground, the traffic is routed to your app even if none of your payment cards were chosen by the user as their default payment card. Quando imposti i criteri di attivazione della carta su ForegroundOverride, questa modifica è solo temporanea fino a quando l’app non è più in primo piano e non verrà cambiata la carta di pagamento predefinita corrente impostata dall’utente.When you change a card’s activation policy to ForegroundOverride, this change is only temporary until your app leaves the foreground and it will not change the current default payment card set by the user. Puoi modificare la proprietà ActivationPolicy per le tue carte di pagamento e non di pagamento dalla tua app in primo piano come illustrato di seguito.You can change the ActivationPolicy of your payment or non-payment cards from your foreground app as follows. Tieni presente che il metodo RequestActivationPolicyChangeAsync può essere chiamato solo da un’app in primo piano e non da un’attività in background.Note that the RequestActivationPolicyChangeAsync method can only be called from a foreground app and cannot be called from a background task.

reg.RequestActivationPolicyChangeAsync(AppletIdGroupActivationPolicy.ForegroundOverride);

Puoi anche registrare un gruppo di AID costituito da un singolo AID di lunghezza 0. In questo modo il sistema indirizzerà tutte le unità APDU indipendentemente dall'AID e includendo qualsiasi unità APDU di comando inviata prima della ricezione del comando SELECT AID.Also, you can register an AID group consisting of a single 0-length AID which will cause the system to route all APDUs regardless of the AID and including any command APDUs sent before a SELECT AID command is received. Un gruppo AID di questo tipo, tuttavia, funziona solo mentre l’app è in primo piano perché può essere impostato solo su ForegroundOverride e non può essere abilitato in modo permanente.However, such an AID group only works while your app is in the foreground because it can only be set to ForegroundOverride and cannot be permanently enabled. Inoltre, questo meccanismo funziona sia per i valori Host che UICC dell’enumerazione SmartCardEmulationType per indirizzare tutto il traffico all’attività in background HCE o alla scheda SIM.Also, this mechanism works both for Host and UICC values of the SmartCardEmulationType enumeration to either route all traffic to your HCE background task, or to the SIM card.

public static byte[] AID_Foreground =
        {};

var appletIdGroup = new SmartCardAppletIdGroup(
                        "Example DisplayName",
                                new List<IBuffer> {AID_Foreground.AsBuffer()},
                                SmartCardEmulationCategory.Other,
                                SmartCardEmulationType.Host);
reg = await SmartCardEmulator.RegisterAppletIdGroupAsync(appletIdGroup);
reg.RequestActivationPolicyChangeAsync(AppletIdGroupActivationPolicy.ForegroundOverride);

Controllare la disponibilità del supporto di NFC e HCECheck for NFC and HCE support

La tua app dovrebbe controllare se un dispositivo dispone di hardware NFC, supporta la funzionalità di emulazione delle carte e supporta l'emulazione delle carte host, prima di offrire tali funzionalità all'utente.Your app should check whether a device has NFC hardware, supports the card emulation feature, and supports host card emulation prior to offering such features to the user.

La funzionalità di emulazione di smart card NFC è abilitata solo in Windows 10 Mobile, quindi qualsiasi tentativo di usare le API dell'emulatore di smart card in altre versioni di Windows 10, causerà errori.The NFC smart card emulation feature is only enabled on Windows 10 Mobile, so trying to use the smart card emulator APIs in any other versions of Windows 10, will cause errors. Per controllare se è disponibile il supporto dell'API per le smart card, puoi usare il frammento di codice seguente.You can check for smart card API support in the following code snippet.

Windows.Foundation.Metadata.ApiInformation.IsTypePresent("Windows.Devices.SmartCards.SmartCardEmulator");

È inoltre possibile verificare se il dispositivo dispone di hardware NFC in grado di eseguire un'emulazione di schede controllando se il metodo SmartCardEmulator. GetDefaultAsync restituisce null.You can additionally check to see if the device has NFC hardware capable of some form of card emulation by checking if the SmartCardEmulator.GetDefaultAsync method returns null. In caso affermativo, il dispositivo non supporta l'emulazione di carte NFC.If it does, then no NFC card emulation is supported on the device.

var smartcardemulator = await SmartCardEmulator.GetDefaultAsync();<

Il supporto del routing HCE e UICC basato su AID è disponibile solo nei dispositivi recenti, come Lumia 730, 830, 640 e 640 XL.Support for HCE and AID-based UICC routing is only available on recently launched devices such as the Lumia 730, 830, 640, and 640 XL. I nuovi dispositivi che supportano NFC ed eseguono Windows 10 Mobile e versioni successive dovrebbero supportare HCE.Any new NFC capable devices running Windows 10 Mobile and after should support HCE. L'app può verificare se è disponibile il supporto HCE come segue.Your app can check for HCE support as follows.

Smartcardemulator.IsHostCardEmulationSupported();

Comportamento con la schermata di blocco o lo schermo spentoLock screen and screen off behavior

Windows 10 Mobile include impostazioni di emulazione delle carte magnetiche a livello di dispositivo, che possono essere impostate dall'operatore di telefonia mobile o dal produttore del dispositivo.Windows 10 Mobile has device-level card emulation settings, which can be set by the mobile operator or the manufacturer of the device. Per impostazione predefinita, l'interruttore "Tocca per pagare" è disabilitato e i "criteri di abilitazione a livello di dispositivo" sono impostati su "Sempre", a meno che questi valori non vengano sovrascritti dall'operatore o dall'OEM.By default, "tap to pay" toggle is disabled and the "enablement policy at device level" is set to "Always", unless the MO or OEM overwrites these values.

L’applicazione può richiedere il valore di EnablementPolicy a livello del dispositivo e agire per ogni caso in base al comportamento desiderato della tua app in ogni stato.Your application can query the value of the EnablementPolicy at device level and take action for each case depending on the desired behavior of your app in each state.

SmartCardEmulator emulator = await SmartCardEmulator.GetDefaultAsync();

switch (emulator.EnablementPolicy)
{
case Never:
// you can take the user to the NFC settings to turn "tap and pay" on
await Windows.System.Launcher.LaunchUriAsync(new Uri("ms-settings-nfctransactions:"));
break;

 case Always:
return "Card emulation always on";

 case ScreenOn:
 return "Card emulation on only when screen is on";

 case ScreenUnlocked:
 return "Card emulation on only when screen unlocked";
}

L'attività in background della tua app verrà avviata anche se il telefono è bloccato e/o lo schermo è spento, solo se il lettore esterno seleziona un AID corrispondente alla tua app.Your app's background task will be launched even if the phone is locked and/or the screen is off only if the external reader selects an AID that resolves to your app. Puoi rispondere ai comandi dal lettore nella tua attività in background, ma se è necessario input da parte dell'utente oppure se vuoi visualizzare un messaggio all'utente, puoi avviare l'app in primo piano con alcuni argomenti.You can respond to the commands from the reader in your background task, but if you need any input from the user or if you want to show a message to the user, you can launch your foreground app with some arguments. L'attività in background può avviare l'app in primo piano con il comportamento seguente.Your background task can launch your foreground app with the following behavior.

  • Sotto la schermata di blocco del dispositivo (l'utente vedrà l'app in primo piano solo dopo aver sbloccato il dispositivo)Under the device lock screen (the user will see your foreground app only after she unlocks the device)
  • Sopra la schermata di blocco del dispositivo (dopo che l'utente chiude la tua app, il dispositivo è ancora in stato di blocco)Above the device lock screen (after the user dismisses your app, the device is still in locked state)
        if (Windows::Phone::System::SystemProtection::ScreenLocked)
        {
            // Launch above the lock with some arguments
            var result = await eventDetails.TryLaunchSelfAsync("app-specific arguments", SmartCardLaunchBehavior.AboveLock);
        }

Registrazione degli AID e altri aggiornamenti per le app basate su SIMAID registration and other updates for SIM based apps

Le app di emulazione di carte magnetiche che usano la SIM come elemento sicuro possono registrarsi nel servizio Windows per dichiarare gli AID supportati nella SIM.Card emulation apps that use the SIM as the secure element can register with the Windows service to declare the AIDs supported on the SIM. Questa registrazione è molto simile a quella per un'app basata su HCE.This registration is very similar to an HCE-based app registration. L'unica differenza è SmartCardEmulationType, che deve essere impostata su UICC per le app basate su SIM.The only difference is the SmartCardEmulationType, which should be set to Uicc for SIM-based apps. In seguito alla registrazione della carta di pagamento, il nome visualizzato della carta sarà popolato anche nel menu delle impostazioni NFC.As the result of the payment card registration, the display name of the card will also be populated in the NFC setting menu.

var appletIdGroup = new SmartCardAppletIdGroup(
                        "Example DisplayName",
                                new List<IBuffer> {AID_PPSE.AsBuffer()},
                                SmartCardEmulationCategory.Payment,
                                SmartCardEmulationType.Uicc);

Importante

Il supporto dell'intercettazione di SMS binari legacy in Windows Phone 8.1 è stato rimosso e sostituito con un nuovo e più ampio supporto per gli SMS in Windows 10 Mobile, ma qualsiasi app di Windows Phone 8.1 legacy che si basa sul vecchio meccanismo deve essere aggiornata per usare le nuove API per gli SMS di Windows 10 Mobile.The legacy binary SMS intercept support in Windows Phone 8.1 has been removed and replaced with new broader SMS support in Windows 10 Mobile, but any legacy Windows Phone 8.1 apps relying on that must update to use the new Windows 10 Mobile SMS APIs.