Handling Results

Working with Payloads

A Payload object contains the data and possible representations that resulted from an image, video, or audio detection. The Payload object also provides the symbology type of the original data that was detected.

Payload Identifiers

Each payload has an identifier that is unique to the symobology detected and the data being carried within the symbol.

The payload identifier may be archived so that an identical Payload object can be later recreated. Alternatively, the Payload object itself can be encoded/decoded for archiving since Payload supports the NSCoding protocol.

Swift

let originalPayloadID = payload.id

// Use the payload's identifier to recreate an identical payload object
let newIdenticalPayload = Payload(identifier: originalPayloadID)

Objective-C

NSString *identifier = [payload identifier];

// Use the payload's identifier to recreate an identical payload object
DMSPayload *newIdenticalPayload = [[DMSPayload alloc] initWithIdentifier:identifier];

Checking the Symbology

The symbology property reveals the type of item detected and contained in the Payload. This allows the developer to know if the detection was a Digimarc Barcode, a traditional 1D barcode, or a QR Code and handle each payload accordingly. For example, the developer may want to use the Resolver to resolve Digimarc Barcodes but may want to open QR Code contents directly within the app.

Swift

let symbology = payload.symbology
if symbology == .upca {
    print("This payload is a UPC-A.")
}

Objective-C

DMSSymbologies symbology = payload.symbology;
if(symbology == DMSSymbologyUPCA) {
    NSLog(@"This payload is a UPC-A.");
}

Retrieving Representations

If the data for a particular symbology can be represented in the format of another symbology, it can be queried from the representations dictionary within Payload. Use the DMPayloadRepresentationType constants for the specific representation to be queried.

Swift

// UPC-A
let representations = payload.representations 
if let upcaRepresentation = representations[PayloadRepresentationType.UPCA] as? String {
    print("The UPC-A is \(upcaRepresentation)")
}
// Weight in Kilograms
if let weightInKilos = representations[PayloadRepresentationType.weightInKilograms] as? Decimal {
    print("The Weight in Kilograms is \(weightInKilos)")
}

Objective-C

// UPC-A
NSDictionary *representations = payload.representations;
if(representations[DMSPayloadRepresentationTypeUPCA]) {
    NSLog(@"The UPC-A is %@", (NSString *)representations[DMSPayloadRepresentationTypeUPCA]);
}
// Weight in Kilograms
if(representations[DMSPayloadRepresentationTypeWeightInKilograms]) {
    NSLog(@"The Weight in Kilograms is %@", ((NSNumber *)representations[DMSPayloadRepresentationTypeWeightInKilograms]).description);
}

Working with GS1 Application Identifiers (AIs)

Payload also carries any applicable GS1 Application Identifiers (AIs). Use the appropriate GS1 Application Identifiers to query the GS1Attributes dictionary for a specific supported AI.

Swift

// The AI Code for GTIN-14 is "01"
let gtin14AI = "01"
if let gtin14 = payload.gs1Attributes[gtin14AI] as? String {
    print("This GS1 AI for GTIN-14 is \(gtin14)")
}

Objective-C

NSString gtin14AI = @"01";
if(payload.GS1Attributes[gtin14AI]) {
    NSLog(@"This GS1 AI for GTIN-14 is %@", payload.GS1Attributes[gtin14AI]);
}

For more information on GS1 Application Ratings or complete specification, refer to the GS1 documentation at gs1.org.

Resolving Payloads (Optional)

A Resolver object retrieves additional metadata associated with a specific Payload from the Digimarc Barcode Resolver. This metadata is not local to the device. Use of the Resolver is not required, however, the resolver will return additional associated metadata such as:

• Title
• Subtitle
• URL
• Thumbnail URL

These items can be displayed in the app’s UI for the user to interact with.

Swift

// Create the resolver object and resolve a Payload object
let resolver = try? Resolver()
resolver?.resolve(payload, queue: OperationQueue.main, completionBlock: { (resolvedContent, error) in

    // Assuming the resolver returned a resolved content object
    if let unwrappedResolvedContent = resolvedContent {

        // Iterate through the resolved content items
        for item in unwrappedResolvedContent.items {

            // Display the additional information in the UI or 
            // handle accordingly to your application's needs
            print("Title: \(item.title)")
            print("Subtitle: \(item.subtitle)")
            print("URL: \(item.url.absoluteString)")
            print("Thumbnail URL: \(item.thumbnailURL.absoluteString)")
        }
    }
)}

Obj-C

NSError *error = nil;
// Create the resolver object and resolve a Payload object
DMSResolver *resolver = [[DMSResolver alloc] initWithOptions:@{} error:&error];
if(error) {
    //handle an error creating the resolver here. this could be something like an invalid API key
    return;
}
[resolver resolve:payload queue:[NSOperationQueue mainQueue] completionBlock:^(DMSResolvedContent * _Nullable resolvedContent, NSError * _Nullable error) {
    if(error) {
        //handle error here
        return;
    }

    // Iterate through the resolved content items
    for(DMSResolvedContentItem *item in resolvedContent.resolvedContentItems) {

        // Display the additional information in the UI or 
        // handle accordingly to your application's needs
        NSLog("Title: %@", item.title);
        NSLog("Subtitle: %@", item.subtitle);
        NSLog("URL: %@", item.url.absoluteString);
        NSLog("Thumbnail URL: %@", item.thumbnailURL.absoluteString);   }
)}

Resolver content metadata is manually entered into the Digimarc Barcode Resolver service by the developer prior to retrieving it using the Resolver object.