Skip to content

Commit 204b659

Browse files
author
Sylvain Maucourt
committed
README.md updated
1 parent 7d32061 commit 204b659

File tree

1 file changed

+60
-44
lines changed

1 file changed

+60
-44
lines changed

‎README.md‎

Lines changed: 60 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,59 @@
11
# Herow SDK Backend
22

3-
[HSB is the SDK backside API](https://github.com/herowio/herow-sdk-backend) helping us to save the world.
3+
## Table of contents
44

5-
It includes several api interacting with [SDK iOS](https://github.com/herowio/herow-sdk-ios) and [SDK Android](https://github.com/herowio/herow-sdk-android).
5+
* [General info](#general-info)
6+
* [Technologies](#technologies)
7+
* [Setup](#setup)
68

7-
![let's go save the world](https://media.giphy.com/media/26BRxBeok96wnAwpy/source.gif)
9+
## General info
810

9-
## How to test it?
11+
[This project is the HEROW's SDK backside API](https://github.com/herowio/herow-sdk-backend).
1012

11-
`node` is also needed, we use `v15.14.0` but should work with lower version.
13+
It includes API needed to interact with [SDK iOS](https://github.com/herowio/herow-sdk-ios) and [SDK Android](https://github.com/herowio/herow-sdk-android).
14+
15+
You can deploy it on AppEngine, Heroku, Kubernetes or on premise.
16+
17+
## Technologies
18+
19+
Project is created with:
20+
21+
- Node _(v15.14.0 - but should work with lower version)_
22+
- Redis 1+
23+
- Kafka 0.10+
24+
25+
## Setup
1226

1327
```
1428
$> brew install node
1529
```
1630

17-
After that, install dependencies and run tests
31+
Clone the project
1832

1933
```
20-
$> npm install
21-
$> npm test
34+
$> git clone [email protected]:herowio/herow-sdk-backend.git
35+
$> cd herow-sdk-backend
2236
```
2337

24-
## How to contribute?
25-
26-
`docker-compose` sets up a Redis and a Kafka instances.
27-
28-
Under macOS, edit `docker-compose.yml` and update `KAFKA_ADVERTISED_HOST_NAME` by setting your local IP. _(localhost should work under Linux)_
38+
Deploy Redis and Kafka via docker
2939

3040
```
31-
$> docker-compose up
32-
$> docker-compose -f docker-compose.yml.arm64 up # for Apple M1
41+
$> docker-compose up # for x86
42+
$> docker-compose -f docker-compose.yml.arm64 up # for M1
3343
```
3444

35-
and…
45+
After that, install dependencies and run it
3646

3747
```
48+
$> npm install
3849
$> npm start
3950
```
4051

41-
# Redis interactions
52+
### Redis interactions
4253

43-
We massively use Redis as database. You have to set a `REDIS_URL` env var to interact with. _(the default value is: redis://127.0.0.1)_
54+
We massively use Redis as database. You have to set a `REDIS_URL` env var to interact with. _(default value: redis://127.0.0.1)_
4455

45-
## identity key
56+
#### Identity key
4657

4758
This key allows to match an SDK instance to a `client`. You can create any client as needed. **You should create a dedicated key for SDK Android and SDK iOS by client and by version**. By this way, you could "stop" easily a specific sdk for a given client.
4859

@@ -57,8 +68,11 @@ We need 4+1 informations :
5768
| username | a dedicated account allowing to use the app | appdemo |
5869
| password | a dedicated password | rtFGHG6$ |
5970

71+
6072
The 5th element is a salt used to hash those informations:
6173

74+
![](https://media.giphy.com/media/l0EoBVexxvaP88SSQ/giphy.gif)
75+
6276
`sha256(TOKEN_SALT, client_id@client_secret@username@password)`
6377

6478
`TOKEN_SALT` env var is used to override salt key _(default is set to secret)_.
@@ -77,44 +91,46 @@ undefined
7791
'd52066c26e3803659e5d1a4b75cdbaab2b26474f371eb17c7e582be67fdca0df'
7892
```
7993

80-
## token key
94+
#### Token key
8195

82-
Every time an SDK generates a token, it is stored with key `token:<token>` and associated with `client`'s identifier (see above). This key is storing during `TOKEN_EXPIRATION` env var _(default is set to 10800 seconds -> 3 hours)_.
96+
After successful authentification, `token` is stored by using key `token:<token>` and associated with the `client`'s identifier _(see above)_. This key is storing during `TOKEN_EXPIRATION` env var _(default is set to 10800 seconds -> 3 hours)_.
8397

84-
## device key
98+
#### Device key
8599

86100
The SDK configuration _(IDFA, customId, optin)_ is stored on key `device:<deviceId>` during `USER_INFO_EXPIRATION` env var _(default is set to 2592000 seconds -> 30 days)_.
87101

88-
## last-modified-cache key
102+
SDK updates those information every day. Meaning that a quiet user is forgotten after 30 days, to prevent privacy.
103+
104+
#### last-modified-cache key
89105

90106
The SDK regularly pulls its configuration.
91-
When cache seems oudated, we can use the key `last-modified-cache:<client>` to order a cache refresh.
107+
When cache seems outdated, we use the key `last-modified-cache:<client>` to order a cache refresh.
92108

93109
`last-modified-cache:<client>` contains timestamp in milliseconds of the last cache update. SDK will decide if it have to refresh it.
94110

95-
## campaigns key
111+
#### Campaigns key
96112

97113
`campaigns:<client>` contains an array of campaigns associated to a given client. If this key is modified, we also should upgrade `last-modified-cache:<client>`.
98114

99-
## zones key
115+
#### Zones key
100116

101-
`zones:<client>:<geohash>` contains an array of "zones" dedicated to a client and to a specific area. [Geohash](https://fr.wikipedia.org/wiki/Geohash) is a 4 digits geocoding code used to parcel the world on 20kmx20km squares. If this key is modified, we also should upgrade `last-modified-cache:<client>`.
117+
`zones:<client>:<geohash>` contains an array of "zones" dedicated to a client and to a specific area. [Geohash](https://fr.wikipedia.org/wiki/Geohash) is a 4 digits geocoding code used to parcel the world on 20x20 km squares. If this key is modified, we also should upgrade `last-modified-cache:<client>`.
102118

103-
## pois key
119+
#### Pois key
104120

105121
`pois:<geohash>` contains a array of "pois" for a given area. Content is shared with every client.
106122

107-
# Kafka interaction
123+
### Kafka interaction
108124

109125
We use Kafka to collect and dispatch LOG from SDKs. You can set `KAFKA_URL` to interact with _(default is set to 127.0.0.1:9092)_. For now, `KAFKA_URL` is a string list of host:port separated by a comma. _(host1:9092,host2:9092,host3:9092)_. *TLS keys and certificates or SASL and are not supported.*
110126

111127
LOG are published on `KAFKA_TOPIC` env var topic _(default is set to stat-logs)_. We use `deviceId` as key and the content of LOG as message.
112128

113-
# API details
129+
### API interaction
114130

115131
![you're my god damn hero](https://media.giphy.com/media/Sv0uzXvg8svM4/source.gif)
116132

117-
## Retrieving an accessToken
133+
#### Retrieving an accessToken
118134

119135
```
120136
▶ http POST http://localhost:8080/auth/authorize/token clientId=test clientSecret=test grantType=password username=test password=test x-version:7.0 x-sdk:test
@@ -135,7 +151,7 @@ X-Powered-By: Express
135151

136152
`export ACCESS_TOKEN=$(http POST http://localhost:8080/auth/authorize/token clientId=test clientSecret=test grantType=password username=test password=test x-version:7.0 x-sdk:test | jq -r .accessToken)`
137153

138-
## Sending user informations
154+
#### Sending user informations
139155

140156
```
141157
▶ http PUT http://localhost:8080/v2/sdk/userinfo x-device-id:test x-sdk:test x-version:7.0 "Authorization: OAuth ${ACCESS_TOKEN}" < userinfo.json
@@ -153,7 +169,7 @@ X-Powered-By: Express
153169
}
154170
```
155171

156-
## Getting configuration
172+
#### Getting configuration
157173

158174
```
159175
▶ http GET http://localhost:8080/v2/sdk/config x-device-id:test x-herow-id:test x-sdk:test x-version:7.0 "Authorization: OAuth ${ACCESS_TOKEN}"
@@ -176,7 +192,7 @@ X-Ref-Date: Sat, 23 Jan 2021 13:25:32 GMT
176192
}
177193
```
178194

179-
## Getting cache
195+
#### Getting cache
180196

181197
```
182198
▶ http GET http://localhost:8080/v2/sdk/cache/content/u09t x-device-id:test x-herow-id:test x-sdk:test x-version:7.0 "Authorization: OAuth ${ACCESS_TOKEN}"
@@ -241,7 +257,7 @@ X-Powered-By: Express
241257
}
242258
```
243259

244-
## Pushing LOG
260+
#### Pushing LOG
245261

246262
```
247263
▶ http POST http://localhost:8080/stat/queue x-device-id:test x-herow-id:test x-sdk:test x-version:7.0 "Authorization: OAuth ${ACCESS_TOKEN}" < log_context.json
@@ -254,9 +270,9 @@ X-Powered-By: Express
254270
X-Ref-Date: Sat, 23 Jan 2021 13:26:41 GMT
255271
```
256272

257-
## LOG format
273+
### LOG format
258274

259-
### CONTEXT
275+
#### CONTEXT
260276

261277
Generated every time a new location is detected
262278

@@ -301,7 +317,7 @@ Generated every time a new location is detected
301317
}
302318
```
303319

304-
### CONTEXT_REALTIME
320+
#### CONTEXT_REALTIME
305321

306322
Generated when "tracking mode" is enabled
307323

@@ -346,7 +362,7 @@ Generated when "tracking mode" is enabled
346362
}
347363
```
348364

349-
### GEOFENCE_ENTER
365+
#### GEOFENCE_ENTER
350366

351367
Sent when a entering zone is detected.
352368

@@ -381,7 +397,7 @@ Sent when a entering zone is detected.
381397
}
382398
```
383399

384-
### GEOFENCE_EXIT
400+
#### GEOFENCE_EXIT
385401

386402
Sent when a exiting zone is detected.
387403

@@ -416,7 +432,7 @@ Sent when a exiting zone is detected.
416432
}
417433
```
418434

419-
### GEOFENCE_VISIT
435+
#### GEOFENCE_VISIT
420436

421437
Sent when a exiting zone is detected.
422438

@@ -448,7 +464,7 @@ This duration is a calculated time between the GEOFENCE_ENTER and GEOFENCE_EXIT
448464
}
449465
```
450466

451-
### GEOFENCE_ZONE_NOTIFICATION
467+
#### GEOFENCE_ZONE_NOTIFICATION
452468

453469
Sent when a notification is displayed.
454470

@@ -485,7 +501,7 @@ Sent when a notification is displayed.
485501
}
486502
```
487503

488-
### REDIRECT
504+
#### REDIRECT
489505

490506
Sent when a notification is opened _(click on it)_.
491507

@@ -505,4 +521,4 @@ Sent when a notification is opened _(click on it)_.
505521
"techno_hash": "1qnn4irqfmghs"
506522
}
507523
}
508-
```
524+
```

0 commit comments

Comments
 (0)