signoAPI iOS – Klasse STLicenceManager

Die Klasse STLicenceManager wird zur Lizenzierung der jeweiligen API-Komponenten libSignoPdfSigner oder libSignoSignatureCapture verwendet. Die Klasse bietet die Möglichkeit, eine Lizenz im neuen UUID-Format (XXXXXXXX–XXXX–XXXX–XXXX–XXXXXXXXXXXX) zu aktivieren, zu aktualisieren, zu übernehmen und freizugeben sowie die Statusinformationen der aktuell verwendeten Lizenz abzufragen. Für Lizenzschlüssel im alten Format verwenden Sie bitte die Methode aus den Klassen und .

Die Lizenz wird mithilfe eines Lizenzschlüssels aktiviert. Nach erfolgreicher Prüfung des Lizenzschlüssels wird die Aktivierung durchgeführt und somit der Demo-Hinweis aus dem Signaturbild und dem Unterschriftendialog entfernt. Sollte sich bei der Prüfung der Lizenz herausstellen, dass bereits die maximale Anzahl an Aktivierungen erreicht wurde, so ist eine kostenpflichtige Erweiterung der Lizenz erforderlich. Alternativ kann eine Aktivierung von einem anderen Gerät übernommen werden, z. B. wenn dieses nicht mehr verwendet wird; hierzu beachten Sie bitte die Methode . Nach Möglichkeit sollte eine Aktivierung vor der Deinstallation aber mit der Methode freigegeben werden, um dieses Problem zu vermeiden.

Es stehen zwei Varianten der Lizenzmethoden zur Verfügung: Eine einfachere Variante ohne Fehlerausgabe, die lediglich einen Statuswert als eine Ganzzahl zurückgibt, sowie eine erweiterte Variante mit einem NSError**-Parameter, die im Fehlerfall detaillierte Fehlerinformationen bereitstellt.

Bei der einfacheren Variante geben alle Methoden zur Aktivierung, Aktualisierung und Freigabe der Lizenz eine Ganzzahl zurück, anhand der erkannt werden kann, ob die jeweilige Methode erfolgreich ausgeführt wurde oder ob ein Fehler aufgetreten ist.

Bei der erweiterten Variante enthalten die Eigenschaften und einen Wert des mit NS_ENUM definierten Enums Error, anhand dessen ein Fehler erkannt werden kann. Dieser Error-Wert ist auch über das von der Methode [] zurückgegebene Objekt zugänglich, genauer gesagt über die Eigenschaft licenceError von STLicenceResult wie folgt: -[[[STLicenceManager getLicenceStatus] licenceResult] licenceError] Bei der Ausführung der Methoden zur Aktivierung, Aktualisierung und Freigabe kann im Fehlerfall ein NSError auftreten. Der entsprechende Fehler und die Fehlermeldung können über das NSError-Objekt abgefragt werden. Das Objekt enthält zusätzliche Informationen im userInfo-Dictionary. Das userInfo-Dictionary des NSError-Objekts enthält unter dem Schlüssel “LicenceError” eine NSNumber, die einen Wert des mit NS_ENUM(NSInteger, LicenceError) definierten Enums LicenceError repräsentiert. Die lokalisierte Fehlermeldung ist über die Eigenschaft localizedDescription des NSError-Objekts verfügbar.

Die Deklaration der Klasse sieht wie folgt aus:

@interface STLicenceManager: NSObject

Das Instanziieren der Klasse STLicenceManager ist nicht über init-Methoden möglich, sondern nur mit der statischen Methode +[].

Methode getLicenceManager:

Von der Klasse STLicenceManager existiert nur eine einzige Instanz (Singletoninstanz), auf die durch diese statische Methode zugegriffen werden kann.

+(STLicenceManager*)getLicenceManager

Anwendung:

STLicenceManager *licenceManager = [STLicenceManager getLicenceManager];

Methode activateLicence:withForceActivation:

Mit dieser Methode kann die Lizenzaktivierung und die Lizenzübernahme durchgeführt werden. Die Lizenzaktivierung erfolgt mithilfe eines Lizenzschlüssels. Nach der erfolgreichen Aktivierung wird der Demo-Hinweis aus dem Signaturbild und dem Unterschriftendialog entfernt. Bitte verwenden Sie den Lizenzschlüssel, der Ihnen von Ihrem Kontakt bei signotec mitgeteilt worden ist, oder bieten Sie dem Anwender die Möglichkeit, einen Lizenzschlüssel einzutragen.

Die Übernahme einer Aktivierung von einem anderen Gerät führt dazu, dass alle Aktivierungen der Lizenz zurückgesetzt und über die regelmäßige Lizenzüberprüfung automatisch im Rahmen der maximalen Anzahl an erlaubten Aktivierungen neu zugeordnet werden. Bitte beachten Sie, dass eine Aktivierung nur ein einziges Mal übernommen werden kann, ohne die App neu installieren zu müssen.

(int)activateLicence:(NSString*)licenceKey withForceActivation:(BOOL)forceActivation

Anwendung:

int ret = [licenceManager activateLicenceKey:@"1234" withForceActivation:NO];
if (ret < 0)
{
    if (ret == -510)
    {
        // activation limit reached, ask user if he wants to transfer 
        // the licence from another device
        // ... 
        if (transfer)
        {
            ret = [licenceManager activateLicenceKey:@"1234" withForceActivation:YES];
        }
        else
        {
            ret = 0;
        }
    }
    if (ret < 0)
    {
        // error handling
    }
}

Methode updateLicence:

Mit dieser Methode können die Eigenschaften der Lizenz erneut abgerufen werden, falls diese sich geändert haben.

(int)updateLicence

Anwendung:

int ret = [licenceManager updateLicence];
if (ret < 0)
{
    // error handling
}

Methode releaseLicence:

Diese Methode bietet die Möglichkeit, die Aktivierung rückgängig zu machen und somit eine Aktivierung freizugeben.

(int)releaseLicence

Anwendung:

int ret = [licenceManager releaseLicence];
if (ret < 0)
{
    // error handling
}

Methode activateLicence:withForceActivation:error

Mit dieser Methode kann die Lizenzaktivierung und die Lizenzübernahme durchgeführt werden. Die Lizenzaktivierung erfolgt mithilfe eines Lizenzschlüssels. Nach der erfolgreichen Aktivierung wird der Demo-Hinweis aus dem Signaturbild und dem Unterschriftendialog entfernt. Bitte verwenden Sie den Lizenzschlüssel, der Ihnen von Ihrem Kontakt bei signotec mitgeteilt worden ist, oder bieten Sie dem Anwender die Möglichkeit, einen Lizenzschlüssel einzutragen.

Die Übernahme einer Aktivierung von einem anderen Gerät führt dazu, dass alle Aktivierungen der Lizenz zurückgesetzt und über die regelmäßige Lizenzüberprüfung automatisch im Rahmen der maximalen Anzahl an erlaubten Aktivierungen neu zugeordnet werden. Bitte beachten Sie, dass eine Aktivierung nur ein einziges Mal übernommen werden kann, ohne die App neu installieren zu müssen.

(void)activateLicence:(NSString*)licenceKey withForceActivation:(BOOL)forceActivation error:(NSError**)error

Anwendung:

NSError *error = nil;
[self.licenceManager activateLicence:licenceKey withForceActivation:NO error:&error];

if (error) {
    NSNumber *errorNumber = error.userInfo[@"LicenceError"];
    if ([errorNumber isKindOfClass:[NSNumber class]]) {
        LicenceError licenceError = (LicenceError)[errorNumber intValue];
        if (licenceError == LicenceErrorActivation_Limit_Reached) {
            NSLog(@"%@", [error localizedDescription]);
            // activation limit reached, ask user if he wants to transfer 
            // the licence from another device
            // ... 
            if (transfer){
               NSError *error1 = nil;
               ret = [licenceManager activateLicenceKey:@"1234" withForceActivation:YES error:&error1];
               if(error1){
                  // error handling
               } else {
                  // transfer successfully executed
               }
            }
        }
    }
} else {
    // license successfully activated
}

Methode updateLicence:error:

Mit dieser Methode können die Eigenschaften der Lizenz erneut abgerufen werden, falls diese sich geändert haben.

(void)updateLicence:(NSError**)error

Anwendung:

NSError *error = nil;
[licenceManager updateLicence:&error];
if (error)
{
    // error handling
} else {
    // license successfully updated
}

Methode releaseLicence:error:

Diese Methode bietet die Möglichkeit, die Aktivierung rückgängig zu machen und somit eine Aktivierung freizugeben.

(void)releaseLicence:(NSError**)error

Anwendung:

NSError *error = nil;
int ret = [licenceManager releaseLicence:&error];
if (error)
{
    // error handling
} else {
    // license successfully released
}

Methode getLicenceStatus

Diese Methode kann verwendet werden, um die Statusinformationen der aktuell verwendeten Lizenz abzufragen.

(STLicenceStatus*)getLicenceStatus

Anwendung:

STLicenceStatus* licenceStatus = [licenceManager getLicenceStatus];
STLicenceResult* licenceResult = licenceStatus.licenceResult;
if (!licenceResult.isSuccessful)
{
    // demo mode
}

Methode getClientIDs

Mit dieser Methode kann die ID abgefragt werden, anhand derer das Gerät vom Lizenzservice identifiziert wird. Sie kann genutzt werden, wenn eine automatische Aktivierung der Lizenz nicht möglich ist. In diesem Fall muss die ID zusammen mit der Rechnungsnummer an lizenz@signotec.de gesendet werden, um eine Lizenzdatei anzufordern.

(NSString*)getClientIDs

Anwendung:

NSString* clientID = [licenceManager getClientIDs];