SDK

The complete developer guide as a PDF document with code examples, can be found here: Developer-Manual

The GpsNose platform is accessible to any developer through the GpsNose open JSON services. You can take the provided C# or PHP reference implementation from this page and:

  • Use it as-is, if you are developing for .NET or PHP, or
  • Write your own custom SDK version for your environment.

The provided SDK can be used:

  • As the source-code, i.e. you can put it into your project as sources and modify/debug/change as you wish, or
  • As a package, i.e. already compiled or packed as a ready-to-go module, available  from within your target environment. For C#, it’s the NuGet library, for PHP it’s (coming soon!)

When you agree, that nobody guarantees you anything and you use the gpsnose.com platform at your own risk, you can download the reference implementation sources for:

The C# library is the very master of the SDKs – it holds the reference implementation, so you can always check for the latest state here. When porting for another environment, the best idea is to take this one.

The EULA you agree with when using the libraries, can be found here.

How it works

Your website can be joined to GpsNose by creating a mashup at the mashup admin. You can use the generated app-key within the GpsNose SDK calls to enable GpsNose functionality for your website’s users, like:

  • Login with the QR-code scanner, available in the mobile app
  • Read the news from your community, primary or sub-communities
  • Use bulletin boards from community comments
  • Show your users the stuff  available nearby, like other community members, impressions, tracks, events, points of interest
  • Use the mashup-tokens for anything you like, like who/what/where was found (scanned), so you can react on your website’s backend reading-in these scanned tokens.

CMS Plugins

We’ve created also a few ready-made CMS plugins, which use the underlying GpsNose SDK for your convenience, so you don’t have to write any custom code.
You are welcome to develop other modules for additional CMS platforms of course, so other web admins can take those without writing code calling the low-level SDK.

See the CMS page for more details.

Quick start

The API is object-oriented and your first class to get to the API calls is always the GnApi:

var api = new GnApi();

The GnApi instance can be reused as many times as you want. Having the GnApi object, you need to decide as who you would like to call the API:

  • As the end-user (your GpsNose SDK-calls on your website run impersonated as the user, which logged into your website with the QR-code or from the mobile APP with the mobile-browser), or
  • As the admin-user (the SDK-calls run as you, the mashup-administrator of your website).

For the administrative tasks, like resetting the mashup-site’s app-key, or adding sub-communities, you can use of course the developer’s console available at the GpsNose website here, but you might want to automate something, like adding and verifying a new mashup site for your account, so all such tasks can be accomplished also using the admin-API calls. Remember, that all such admin tasks require you to be logged-in of course.

On the other hand, the end-user can login into your website using his GpsNose mobile-app, scanning the QR-code (will be discussed later) from your website. Or, he can login directly from his GpsNose mobile-app, from within the community-details window: he is then redirected straight to your website on his mobile phone (i.e. using the mobile’s web-browser). Then your website can enter/read the data in his name, so he sees other users and things in his real nearby area, like impressions, tracks, events etc.

The end-user can also call some services as a guest, so the corresponding sink object GnLoginApiEndUser can be in a not-logged-in state.

Both the GnApi.GetLoginApiForAdmin() and GetLoginApiForEndUser() work similarly. When called, you can provide your own loginId for identifying the login-session, which is simply an alphanumerical random string, at least 10 chars long, or you can leave it empty, to get a new Guid string from the SDK. It’s just a session-id, which identifies globally (worldwide, not just within your website) a user, after he logs-in.

Both the GnLoginApiBase objects – GnLoginApiAdmin and GnLoginApiEndUser –  gets you  to the needed API services.

Here is an example of how to wait for a user-login from your website:

// get the GN platform api
var api = new GnApi();

// get the end-user login-api
var loginApi = api.GetLoginApiForEndUser(_site.AppKey);

// generate the QR-code for login
var qrCode = loginApi.GenerateQrCode();

// TODO: here, you must show the user the QR-code so he can scan it

// set max wait-time as 1 minute for example
var cancelSource = new CancellationTokenSource(1 * 60 * 1000);

// wait for the end-user to log-in with scanning the QR-code
var task = loginApi.WaitForLogin(cancelSource.Token);
try
{
    task.Wait();
}
catch (OperationCanceledException)
{
    // cancelled by time-out or user-cancelled: do nothing..
    throw new Exception("user didn't log-in");
}

// in the result, the user-data is returned for your needs
var userData = task.Result;

When you need to show some general data to the anonymous user, who is currently not logged-in, you can do it like in this news-reading example:

// get the GN platform api
var api = new GnApi();

// get the end-user login-api, which will stay in a not-logged-in state in this example
var loginApi = api.GetLoginApiForEndUser(_site.AppKey);

// get the news-api, which is an guest-enabled api
var newsApi = loginApi.GetNewsApi();

// get the news
var news = newsApi.GetNewsPage();

To sum it up, some services need:

  • An administrative login (for an automated mashup management), other need
  • An end-user login (such as the GnNearbyApi services), as there must be an already logged-in user (for example, to explore his real nearby area) and some service even
  • Don’t need a login at all (like reading the news) and thus they can be called without having the LoginApi been in a logged-in state.

The service-calling steps:

  1. Use the GnApi to get to the GnLoginApiBase, for both the admin and end-user API call-areas,
  2. Wait for the user-login if needed so,
  3. Access the underlying services, which are either administrative, or user-scoped, or even guest-enabled.

Caching and Quotas

Most of the SDK API-calls are cache-enabled, which means: if the same API-request parameters were already been used a short time ago (default is 15 minutes), the response is read from the SDK’s cache, instead of contacting the GpsNose server.

The advantage of this is:

  • Saving time/traffic costs needed for contacting the external web service and
  • Saving your monthly calling quotas on the GpsNose server side.

As GpsNose is free for anybody (well, as long as we can pay for it ourselves..), we must ensure some website with high traffic won’t make us bankrupt ;-). So there are some calling-quotas applied for your website, which can be seen and monitored in the developer console here.

Paging

A lot of APIs use the time-based paging, like in the aforementioned reading-news example. The data-page you get contains a data-segment from a given time-point, let’s say 20 items in the page. Then, you can page-through to the next-page supplying the API the lastKnownTicks parameter, which is the first item’s creation ticks you have received before, as the first item is the very latest one.

Consider the following read-news example, this time paging through all the available news:

// get the GN platform api
var api = new GnApi();

// get the end-user login-api, which will stay in a not-logged-in state in this example
var loginApi = api.GetLoginApiForEndUser(_site.AppKey);

// get the news-api, which is an guest-enabled api
var newsApi = loginApi.GetNewsApi();

// get the news
var news = newsApi.GetNewsPage();

// continue reading, until more news-data keeps coming
while (news.Count > 0)
    news = newsApi.GetNewsPage(lastKnownTicks: news[0].CreationTicks);

How you can help

When you write your own SDK for other systems (Java, Node.JS etc.), you’re welcome to publish your code somewhere (e.g. GitHub) and tell us we can link it from this page.

We have no available resources to code or maintain more code as we already do already. But when you can help with creating new libraries, we can support you more focused using GpsNose API/SDK and maybe give you some goodies, like more relaxed API calling quotas for example.

SDK Versioning

1.0.53
– ADD: AddSubCommunity() now supports ACLs specification

1.0.52
– FIX: GnAdminApi ctor, GnLoginApiAdmin access

1.0.51
– ADD: GnMailsApi, GnMail: sending and reading mails

1.0.50
– FIX: https links for NuGet

1.0.49
– UPD: API calls examples/params set to geohamster.com
– ADD: GnMashupTokensApi.GetMashupTokensPage() lastKnownScanTicks default = 0
– UPD: readme.txt

1.0.48
– FIX: GnAdminApi.UpdateCommunityWeb(): added the missing mashupTokenCallbackUrl

1.0.47
– UPD: readme.txt

1.0.46
– ADD: readme.txt

1.0.45
– ADD: GnMashupToken.CallbackResponseHttpCode, GnMashupToken.CallbackResponseMessage
– DEL: GnMashupToken.CallbackResponse
– ADD: UpdateCommunityWeb() -> mashupTokenCallbackUrl param for defining the optional scan-callback-url

1.0.44
– ADD: GnMashup.MashupTokenCallbackUrl optional property for sync-calling mashup’s callback-url
– ADD: GnMashupToken.CallbackResponse the response from the mashup’s callback

1.0.43
– DOC: NuGet package metadata

1.0.42
– REF: GenerateQrCode() available as separate functions for admin/endUser login-apis

1.0.41
– REF: GnLoginApi -> GnLoginApiBase + GnLoginApiEndUser + GnLoginApiAdmin

1.0.40
– REF: GnMashupTokensApi

1.0.39
– ADD: GnAdminApi.GenerateQrTokenForMashup(): validToTicks

1.0.38
– ADD: GnAdminApi.GetMashupTokensPage()

1.0.37
– ADD: GnAdminApi.GenerateQrTokenForMashup() for generating a QR-code for a mashup

1.0.36
– REF: error-handling in GnApiModuleBase.ExecuteCall()
– ADD: GnCommunityApi.InviteMemberToCommunity()

1.0.35
– REF: GnCreatedEntity -> GnAroundObject

1.0.34
– FIX: nearby-noses: no-caching

1.0.33
– UPD: nearby-items are not cached at all

1.0.32
– FIX: err-responses (httpErr, jsonErr) and null-responses are now not cached

1.0.31
– REF: GnNose derived from GnCreatedItem => Noses-around now have:
.. .Creator instead of .LoginName
.. .CreationTicks for last-touch
– ADD: created-items around API calls: now having DistanceExact if available

1.0.30
– FIX: QUOTA_MAX_CALLS = 3

1.0.29
– FIX: HandleCallQuota(): if (_quota_CallCounter > QUOTA_MAX_CALLS): comparison fixed to “>=”

1.0.26
– ADD: GenerateQrCodeForCommunityJoin caching-ttl=1day

1.0.25
– ADD: GnCommunityApi.GenerateQrCodeForCommunityJoin

1.0.24
– ADD: GnUtility.ToExpando()

1.0.23
– ADD: GnApiModuleBase.ClearCacheForActionNames()
– FIX: GnCommentsApi.UpdateComment()/AddComment() clearing the GetCommentsPage()
– FIX: GnApiModuleBase.ExecuteCall() overload now using cacheTtl

1.0.22
– ADD: GnApiModuleBase.ClearCacheForActionName()
– UPD: GnCommentsApi.UpdateComment()/AddComment() clearing the cache

1.0.21
– ADD: GnCache.ClearCache + optional key-pattern matching for delete-in-scope

1.0.20
– FIX: caching turned off for GnCommentApi.AddComment/UpdateComment and GnLoginApi.GetVerified/CheckIfIsStillLoggedId

1.0.19
– ADD: caching-policy for GnApiModuleBase.SimpleResultCall
– ADD: no-caching option: TimeSpan.MaxValue
– FIX: caching-policy for GnAdminApi: GetOwnMashups = 1sec, other calls: no-caching

1.0.18
– UPD: default langId: current instead of “en”

1.0.17
– ADD: caching for GnApiModuleBase.ExecuteCall()

1.0.16
– ADD: GnUtility.GetQueryStringFromKeyVals
– ADD: GnLogin.LangId
– UPD: GnApiModuleBase.Execute: langId scope

1.0.15
– ADD: JsonTool.QuickJson()

1.0.14
– ADD: IsLoggedIn: nullable<bool> for tri-state

1.0.13
– ADD: GnSettings.CurrentLangId

1.0.11
– ADD: GnCommunity.Admins

1.0.10
– UPD: PageNews: int->int? pageSize
– REF: MembersPage -> GetMembersPage

1.0.9
– ADD: GnSettings.IsSuperNoseMachine dev-helper

1.0.8
– ADD: GnLocalSettings

1.0.7
– REF: GnPaths: details/images

1.0.6
– DEL: GnPaths: LoginQrImage path: deprecated, use API call to generate it

1.0.5
– UPD: WaitForLogin is async now

1.0.4
– UPD: ex message on GenerateQrCode(): if comm is not provided for normal user

1.0.3
– UPD: async WaitForLogin

1.0.2
– UPD: WaitForLogin can be aborted from outside

1.0.1
– UPD: QR-code received test on calling login methods

1.0.0
– ADD: Initial Release