Asset Tracking GRPC Streaming API (Go) Follow

This version of the Tag Tracker was released recently. This guide will help you getting started using the new API. This document uses Go, but there is a Python Example as well.

1. Download the track.proto file attached to this doc. This will give you our model definitions and allow you to generate models and gRPC calls in your language of choice.
2. track.proto imports some common Google protobufs, so you'll need to clone the grpc-gateway repo and make sure it's in your import path.
3. Follow the Go Quick Start Guide to get gPRC running in a virtual environment on your machine. For our setup, we run a Makefile that contains the following script:

   protoc -I ./tracking \
    -I$(GOPATH)/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
    --grpc-gateway_out=logtostderr=true:<location for output> \
    --go_out=plugins=grpc:<location for output> \
   track.proto

4. Create an Application Token for the Meridian Location you want to access.
5. Select the correct hostname for your region:
   Europe: tags-eu-direct.meridianapps.com
   All others: tags-direct.meridianapps.com
6. Now let's look at an example on how to grab all assets in a single pull:

   func TestGetAllAssets_ClientIntegration(t *testing.T) {
       if testing.Short() {
          t.SkipNow()
       }
       config := &tls.Config{}
       creds := credentials.NewTLS(config)
       conn, err := grpc.Dial("tags-direct.meridianapps.com:50051", grpc.WithTransportCredentials(creds))
       if err != nil {
          t.Fatal(err)
       }
       defer conn.Close()
       ctx := context.Background()
       ctx = metadata.AppendToOutgoingContext(
          ctx,
          "authorization",
          "Token <your application token>",
       )
       client := track.NewTrackingClient(conn)
       request := &track.AllAssetRequest{
          LocationId: "<your location id>",
       }
       assetList, err := client.GetAllAssets(ctx, request)
       if err != nil {
          t.Fatal(err)
       }
    }

   As you will notice, we are taking the Client TLS cert, dialing up to our gRPC endpoint at 50051, and using our auth credentials in the context for our request.

7. Now let's look at an example on how to dial up to an ongoing tracking stream:

   func TestTrackAssets_ClientIntegration(t *testing.T) {
       if testing.Short() {
          t.SkipNow()
       }
       config := &tls.Config{}
       creds := credentials.NewTLS(config)
       conn, err := grpc.Dial("tags-direct.meridianapps.com:50051", grpc.WithTransportCredentials(creds))
       if err != nil {
          t.Fatal(err)
       }
       defer conn.Close()
       ctx := context.Background()
       ctx = metadata.AppendToOutgoingContext(
          ctx,
          "authorization",
          "Token <your application token>",
       )
       client := track.NewTrackingClient(conn)
       request := &track.AssetRequestList{
          AssetRequests: []*track.AssetRequest{
             {
                ResourceType: track.AssetRequest_LOCATION,
                LocationId:   "<your location id>",
             },
          },
       }
       stream, err := client.TrackAssets(ctx, request)
       if err != nil {
          t.Fatal(err)
       }
    }

8. For more specifics on how to scope requests, or how to subscribe, consult the attached protobuf, track.proto.

Note: Unlike the previous tag-tracking, we now handle all subscriptions in our first request, meaning there are no subsequent changes to be made to a running stream. If you would like to unsubscribe to a certain floor, location, etc, you will want to disconnect and send a new request.

To see the JSON output of these APIs, or further details on the REST endpoint, visit our Tag Tracker sandbox: https://tags.meridianapps.com/docs/track

The previous version of the proto file, track_legacy.proto, did not include latitude and longitude values and is included here purely for historical reasons.