Endpoint profile is a virtual identity or "passport" of the endpoint. By filtering against the data in the profiles, endpoints may be aggregated into independently managed groups. Please review the Kaa profiling design reference for more background.
This guide will familiarize you with the basic concepts of designing endpoint profiles and programming the Kaa profiling subsystem. It is assumed that you have either set up a Kaa Sandbox, or a full-blown Kaa cluster already and that you have created a tenant and an application in Kaa.
The following diagram illustrates basic entities and data flows in scope of the endpoint profile management:
The default client-side profile schema installed for Kaa applications is empty. In order to make use of the Kaa profiling / identity management capabilities, you should load at least either client-side or server-side profile schema that reflects the application you are designing. Please note that client-side structure is used during SDK generation and changes to the client-side structure requires generation of new SDK. However, Application developer is able to define and change server-side structure of endpoint profile at any time.
Think about the client-side profile schema as of a structured data set of your endpoint application that will later be available to you in Kaa server and may change due to your client application logic or device state.
You can configure your own client-side profile schema using the Admin UI or REST API. For the purpose of this guide we will use a fairly abstract client-side profile schema shown below.
{ "type":"record", "name":"Profile", "namespace":"org.kaaproject.kaa.schema.sample.profile", "fields":[ { "name":"id", "type":"string" }, { "name":"os", "type":{ "type":"enum", "name":"OS", "symbols":[ "Android", "iOS", "Linux" ] } }, { "name":"os_version", "type":"string" }, { "name":"build", "type":"string" } ] }
Client-side endpoint profile updates are reported to the endpoint SDK using a profile container. The profile related API varies depending on the target SDK platform, however the general approach is the same.
import org.kaaproject.kaa.client.Kaa; import org.kaaproject.kaa.client.KaaClient; import org.kaaproject.kaa.client.profile.ProfileContainer; import org.kaaproject.kaa.client.DesktopKaaPlatformContext; import org.kaaproject.kaa.schema.sample.profile.OS; import org.kaaproject.kaa.schema.sample.profile.Profile; // Profile is an auto-generated class based on user defined schema. Profile profile; // Desktop Kaa client initialization public void init() { // Create instance of desktop Kaa client for Kaa SDK KaaClient client = Kaa.newClient(new DesktopKaaPlatformContext(), new SimpleKaaClientStateListener()); // Sample profile profile = new Profile("id", OS.Linux, "3.17", "0.0.1-SNAPSHOT"); // Simple implementation of ProfileContainer interface that is provided by the SDK client.setProfileContainer(new ProfileContainer() { @Override public Profile getProfile() { return profile; } }); // Starts Kaa client.start(); // Update to profile variable profile.setBuild("0.0.2-SNAPSHOT"); // Report update to Kaa SDK. Force delivery of updated profile to server. client.updateProfile(); }
#include <memory> #include <kaa/Kaa.hpp> #include <kaa/profile/DefaultProfileContainer.hpp> using namespace kaa; ... // Create instance of Kaa client for Kaa SDK auto kaaClient = Kaa::newClient(); // Profile is an auto-generated class based on user defined schema. Profile profile; // Sample profile profile.id = "id"; profile.os_version = "3.17"; profile.os = OS::Linux; profile.build = "0.0.1-SNAPSHOT"; // Simple implementation of ProfileContainer interface that is provided by the SDK auto profileContainer = std::make_shared<DefaultProfileContainer>(profile); kaaClient->setProfileContainer(profileContainer); // Starts Kaa kaaClient->start(); // Update to profile variable profile.build = "0.0.2-SNAPSHOT"; profileContainer->setProfile(profile); // Report update to Kaa SDK. Force delivery of updated profile to server. kaaClient->updateProfile();
#include <kaa/platform/kaa_client.h> #include <kaa/kaa_profile.h> #define KAA_EXAMPLE_PROFILE_ID "id" #define KAA_EXAMPLE_OS_VERSION "3.17" #define KAA_EXAMPLE_BUILD "0.0.1-SNAPSHOT" #define KAA_EXAMPLE_NEW_BUILD "0.0.2-SNAPSHOT" static kaa_client_t *kaa_client = NULL; // Profile is an auto-generated class based on user defined schema. static kaa_profile_t *profile = NULL; ... // Create instance of Kaa client for Kaa SDK kaa_client_create(&kaa_client, NULL); ... // Sample profile profile = kaa_profile_profile_create(); profile->id = kaa_string_move_create(KAA_EXAMPLE_PROFILE_ID, NULL); profile->os = ENUM_OS_Linux; profile->os_version = kaa_string_move_create(KAA_EXAMPLE_OS_VERSION, NULL); profile->build = kaa_string_move_create(KAA_EXAMPLE_BUILD, NULL); // Pass profile before client is started kaa_profile_manager_update_profile(kaa_client_get_context(kaa_client)->profile_manager, profile); ... // Starts Kaa kaa_client_start(kaa_client, /* user routine */, /* user context */, /* calling frequency of user routine */); ... // Update to profile variable profile->build = kaa_string_move_create(KAA_EXAMPLE_NEW_BUILD, NULL); kaa_profile_manager_update_profile(kaa_client_get_context(kaa_client)->profile_manager, profile); ... profile->destroy(profile); profile = NULL;
#import <Kaa/Kaa.h> #import "ViewController.h" @interface ViewController () <ProfileContainer> @property (nonatomic, strong) KAAProfile *profile; @end @implementation ViewController - (void)initClient() { // Create instance of Kaa client id<KaaClient> client = [Kaa client]; // Sample profile that is an auto-generated class based on user defined schema. _profile = [[KAAProfile alloc] initWithId:@"id" os:OS_LINUX code:@"3.17" build:@"0.0.1-SNAPSHOT"]; // Simple implementation of ProfileContainer interface that is provided by the SDK [client setProfileContainer:self]; // Starts Kaa [client start]; // Update to profile variable _profile.build = @"0.0.2-SNAPSHOT"; // Report update to Kaa SDK. Force delivery of updated profile to server. [client updateProfile]; } - (KAAProfile *)getProfile { return _profile; } ... @end
Think about the server-side profile schema as of a set of your endpoint properties the are controlled by your server-side applications. For example, client subscription plan, device activation flag, etc. You may also use server-side endpoint profile to store properties that are set during manufacturing and should not be controlled by client application.
You can configure your own server-side profile schema using the Admin UI or REST API. For the purpose of this guide we will use a fairly abstract server-side profile schema shown below.
{ "type":"record", "name":"ServerProfile", "namespace":"org.kaaproject.kaa.schema.sample.profile", "fields":[ { "name":"subscriptionPlan", "type":"string" }, { "name":"activationFlag", "type":"boolean" } ] }
Once this schema is configured, you are able to assign server-side endpoint profile body to certain endpoints based on their ids using Admin UI or REST API.
Copyright © 2014-2015, CyberVision, Inc.
5 Comments
Bin.Zhang
It's not clear where and how the server profile is used after the schema is defined? while it's easy to understand the client profile is used by client SDK.
singleye
"Think about the server-side profile schema as of a set of your endpoint properties the are controlled by your server-side applications"
From my understanding, it's a piece of information related with the endpoint, it's supposed to be used by the server-side. And after searching the SDK code, I think the server profile is not synced to the client side.
Correct me if I'm wrong.
Denis Cherneta
as I understood, server-profile using in Endpoint grouping
singleye
Agree
alf cee
修改了Client-side EP profile,需要重新修改SDK profile才能生效