mirror/Android
1
0
Fork 0
mirror of https://github.com/CatimaLoyalty/Android.git synced 2026-04-14 04:17:27 -04:00
Code Issues Packages Projects Releases Wiki Activity

Migrate dev docs to git repository

Browse Source 
This allows us to deprecate https://github.com/CatimaLoyalty/Docs and
keep everything together
This commit is contained in:
Sylvia van Os
2025-12-25 17:56:39 +01:00
parent 64a31b5729
commit 1a8c6d6e90
3 changed files with 131 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/CARD_FIELDS.md Normal file
View File

@@ -0,0 +1,21 @@
# Card fields
These are the fields available in a card.
An [export](./EXPORT_FORMAT.md) always contains all values. A [card sharing URL](./CARD_SHARING_URL_FORMAT.md) only contains some of the values.
| Key | In sharing URL | Valid values | Explanation |
| ----------- | -------------- | ------------ | ----------- |
| store | Required | Any string | Name of the store this card belongs to |
| note | Required | Any string | An optional note for the end-user |
| validfrom | Optional | Any UNIX timestamp | When the loyalty card starts being valid |
| expiry | Optional | Any UNIX timestamp | When the loyalty card expires |
| balance | Optional | Any string value accepted by Java's BigDecimal constructor | The balance available in the loyalty card |
| balancetype | Optional | Any valid ISO 4217 value or unset for "Points" | The balance currency (USD, EUR, etc.) or "points" |
| cardid | Required | Any string | The loyalty card ID |
| barcodeid | Optional | Any string | The value of the loyalty card barcode, if different from the loyalty card ID |
| barcodetype | Optional | AZTEC, CODABAR, CODE_39, CODE_93, CODE_128, DATA_MATRIX, EAN_8, EAN_13, ITF, MAXICODE, PDF_417, QR_CODE, RSS_14, RSS_EXPANDED, UPC_A, UPC_E | The type of loyalty card barcode used |
| headercolor | Optional | A valid Android color value (https://developer.android.com/reference/android/graphics/Color) | The color to use in the header and card background |
| starstatus | Ignored | 0,1 | If the card is "starred" |
| lastused | Ignored | Any UNIX timestamp | When the loyalty card was last opened |
| archive | Ignored | 0,1 | If the card should be marked as archived |

49
docs/CARD_SHARING_URL_FORMAT.md Normal file
View File

@@ -0,0 +1,49 @@
# Card sharing URL format
In the interest of interoperability, this page documents the URLs generated when sharing a card.
URLs have the following parts:
## hostname and path
Hostname and path must be any of the following combinations:
| Hostname | Path | Description |
| ------------------------ | -------------------------- | ---------------------------------------------------------------------- |
| catima.app | /share | Default since 2021-07-11 |
| thelastproject.github.io | /Catima/share | Created when forking away from Loyalty Card Keychain |
| brarcher.github.io | /loyalty-card-locker/share | For compatibility with https://github.com/brarcher/loyalty-card-locker |
## parameters
The list of supported fields are listed in [Card fields](./CARD_FIELDS.md).
## Catima 2.0
As of Catima 2.0, Share URLs are in the following format for increased privacy (no leaking card info to the server):
```
https://[hostname]/[path]#[parameters]
```
Parameters are written as such before being url-encoded (so yes, the values are url-encoded twice)
```
key=urlencoded_value&key2=urlencoded_value2
```
An example share URL is as follows:
```
https://catima.app/share#store%3DGrocery%2BStore%26note%3DQuite%2Bnecessary%26balance%3D150%26cardid%3Ddhd%26barcodetype%3DAZTEC%26headercolor%3D-9977996
```
## Before 2.0
Share URLs are in the following format:
```
https://[hostname]/[path]?[parameters]
```
An example share URL is as follows:
```
https://catima.app/share?store=Grocery%20Store&note=Quite%20necessary&balance=150&cardid=dhd&barcodetype=AZTEC&headercolor=-9977996
```
These are still imported for backwards compatibility, but no longer generated.

61
docs/EXPORT_FORMAT.md Normal file
View File

@@ -0,0 +1,61 @@
# Export format
Since version 2.0, a Catima export is a Zip file containing:
1. A single catima.csv file
2. All image files as .png
Continue reading for more details about both.
Before 2.0, the backup format was just the .csv file, not inside a .zip file. It can still be imported in 2.0+. To import a 2.0+ backup into older Catima versions, one should extract the .csv file and import that instead.
## catima.csv
The catima.csv file is a CSV file in the following format:
```
[version number]
[group database table description]
[one line per group]
[card database table description]
[one line per card] (may contain a multi-line note)
[card to group linking database table description]
[one line per link]
```
Version number is always 2. If a database table is empty, there are simply no lines. For valid possible values for each table, see [Card fields](./CARD_FIELDS.md). Do keep in mind that, depending on the Catima version, some fields may not be supported and thus missing from the export. You should treat all the fields you don't need as optional.
Example full export:
```
2
_id
Health
Food
Fashion
_id,store,note,validfrom,expiry,balance,balancetype,cardid,barcodeid,barcodetype,headercolor,starstatus,lastused,archive
1,Clothing Store,Note about store,,,0,,qw,,,-45147,1,1730493938,0
2,Department Store,,,,0,,A,,,-1499549,0,1730493491,0
3,Grocery Store,,,1453633200000,50,,dhd,,,-11751600,0,1730493369,0
4,Pharmacy,,,,0,,dhshsvshs,,,-16766866,0,1684347330,1
5,Restaurant,Note about restaurant here,,,0,,98765432,,CODE_128,-10902850,0,1730493357,0
6,Shoe Store,,,,0,,zhxbx,,AZTEC,-6543440,0,1684347744,0
cardId,groupId
8,Fashion
3,Food
4,Health
5,Food
6,Fashion
```
## Image files
The image files are named using the following pattern:
```
card_<id>_<side>.png
```
With id referring to the id of the loyalty card it belongs to and side being either `front`, `back` or `icon`.