Introduction
The truemetrics SDK supports logging of not only sensor data but also metadata from your mobile application. This allows you to enrich truemetrics data with specific courier events and data to get most of truemetrics data.When to send metadata and what to use as trigger
When is the right time to send metadata? The truemetrics algorithm matches the metadata closest in time to the stop event. Most customers choose an interaction that occurs close to the actual service, such as scanning the parcel or the courier swiping to confirm arrival at the delivery location. Try to avoid triggers that the driver might often forget, such as marking the delivery as closed or starting navigation to the next stop, as this can lead to mismatches between the metadata and the stop data in truemetrics. If you’re unsure, either discuss this with truemetrics or use multiple triggers to send metadata. Just make sure to include the type of trigger so that the data is not interpreted as multiple deliveries.| Example Key | Example Value |
|---|---|
| type_trigger | job_finalized / scan_performed |
| … | … |
How to send metadata
Basic metadata logging:Required Metadata Fields
Normalized Addresses
For validation, the normalized address of the delivery is required to be logged into the truemetrics data. It is best practice to send an object similar to the following example:| Example Key | Example Value |
|---|---|
| country_code | DE |
| postal_code | 10762 |
| street | Pflanzstrasse |
| house_number | 5 |
Identifiers
Most customers already have internal identifiers for deliveries, parcels, tours, and other related entities. truemetrics automatically enriches stop KPIs, parking spots, and entrances by using these identifiers. This makes it easier you to track, check, and evaluate truemetrics data.| Example Key | Example Value |
|---|---|
| identifier_driver | 1kl234abc |
| identifier_tour | 4d1234abc |
| identifier_delivery | 0a1234abc |
| identifier_stop | 531234abc |
| … | … |
Reference Location
The truemetrics algorithm does not rely on the location to which you are sending your driver. Nevertheless, in the early stages of integration, many customers find it useful to compare the actual delivery location with the expected location to assess the accuracy of the address and geocoder.| Example Key | Example Value |
|---|---|
| lat | 40.3123 |
| lon | 13.533 |
Additional Best Practices
Service Type
Stop times can vary significantly depending on the type of service performed. Was it a fast B2B drop-off with a single parcel, or a more complex B2C pickup requiring a signature? You know best what is important for your business, and truemetrics allows you to enrich the data with your specific categories, enabling you to later analyze the data based on those categories. Typical examples:| Example Key | Example Value |
|---|---|
| type_consignee | B2C |
| type_stop | pickup (or drop-off) |
| type_service | E42c (internal code) |
Vehicle types
Some of our customers have multiple vehicle types e.g. Trucks, cars and two-wheelers. Especially for parking places, it’s quite interesting to be able to seperate this data by the type of the vehicle. To do that, just introduce a new key-value pair and log the vehicle type.| Example Key | Example Value |
|---|---|
| type_vehicle | car |
Advanced Metadata Features
Metadata Templates
Create reusable templates for consistent metadata structures:Tagged Metadata
Build metadata incrementally using tags:Tagged Metadata API Reference
| Method | Return Type | Description |
|---|---|---|
createMetadataTemplate(name, data) | Unit | Create reusable template |
getMetadataTemplate(name) | Map<String, String>? | Get template by name |
getMetadataTemplateNames() | Set<String> | List all templates |
removeMetadataTemplate(name) | Boolean | Remove template |
createMetadataFromTemplate(tag, template) | Boolean | Create tag from template |
appendToMetadataTag(tag, data) | Unit | Append map to tagged metadata |
appendToMetadataTag(tag, key, value) | Unit | Append single key-value to tag |
getMetadataByTag(tag) | Map<String, String>? | Get tagged metadata |
getMetadataTags() | Set<String> | Get all active tags |
logMetadataByTag(tag) | Boolean | Log tagged metadata |
removeMetadataTag(tag) | Boolean | Remove tag |
removeFromMetadataTag(tag, key) | Boolean | Remove key from tag |
clearAllMetadata() | Unit | Clear all templates and tags |