Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .github/workflows/deploy.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,21 @@ jobs:
uses: actions/checkout@v4
with:
token: ${{ steps.app-token.outputs.token }}
# Two commits, so the step below can diff HEAD against its parent.
fetch-depth: 2

- name: Tag if version is new
if: steps.ready.outputs.ready == 'true'
run: |
# Tag only the commit that introduced the version. This job runs on
# every push to the trunk, so most runs read a pubspec that was tagged
# releases ago — harmless while that tag exists, but the moment one is
# missing it would pin the old name onto a much later commit.
if ! git diff --name-only HEAD~1 HEAD | grep -qx 'pubspec.yaml'; then
echo "pubspec.yaml unchanged in HEAD — not a release commit"
exit 0
fi

VERSION=$(grep '^version:' pubspec.yaml | awk '{print $2}')
TAG="v$VERSION"
if git ls-remote --exit-code --tags origin "refs/tags/$TAG" \
Expand Down
16 changes: 9 additions & 7 deletions .github/workflows/sync.yaml
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
name: Repository synchronization

# Triggered by the release commit itself rather than by the completion of the
# Deploy workflow. Deploy completes on every push to the trunk — once for the
# change, once again for the release commit — so a single release used to reach
# the mirror as two synchronization PRs carrying the same version.
on:
workflow_run:
workflows:
- Deploy
types:
- completed
push:
branches:
- master
workflow_dispatch:

jobs:
prepare:
if: |
!contains(github.repository_owner, 'personaclick') &&
(github.event_name == 'workflow_dispatch' ||
github.event.workflow_run.conclusion == 'success') &&
!contains(github.repository_owner, 'personaclick')
startsWith(github.event.head_commit.message, 'chore(release):'))
runs-on: ubuntu-latest
outputs:
replacements: ${{ steps.getReplacementsStep.outputs.replacements }}
Expand Down
195 changes: 195 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,201 @@ without an id resolves only while exactly one shop is registered, and throws
never registered).


## Track events

Standard events live in the `tracking` namespace of the handle:

```dart
await sdk.tracking.productView('sku-1');
```

Each method returns a `Future<void>` that completes once the native SDK has the
API's answer; a rejected request throws a `PlatformException` (`track_failed`, or
`track_event_failed` / `track_purchase_failed` for custom events and orders).
Awaiting is optional — fire-and-forget from UI code is fine.

With several shops the namespace follows the instance:

```dart
await Rees46.getInstance('shop-b').tracking.productView('sku-1');
```

### Catalog

```dart
// Product page opened.
await sdk.tracking.productView('sku-1');

// Category listing opened.
await sdk.tracking.categoryView('boots');

// The user searched. Pass `results` when your app runs the search itself and
// knows the ids it showed.
await sdk.tracking.search('winter boots', results: ['sku-1', 'sku-2']);
```

### Cart

```dart
// One product added.
await sdk.tracking.addToCart(
const TrackingItem(id: 'sku-1', quantity: 2, price: 49.9, fashionSize: '42'),
);

// The cart as it looks after a change — replaces the stored contents.
await sdk.tracking.syncCart(const [
TrackingItem(id: 'sku-1', quantity: 2, price: 49.9),
TrackingItem(id: 'sku-2'), // quantity defaults to 1
]);

// One product removed.
await sdk.tracking.removeFromCart('sku-1');
```

`TrackingItem` needs only an `id`; `quantity` defaults to `1`, `price` and
`fashionSize` are optional.

### Favorites

```dart
await sdk.tracking.addToFavorites('sku-1');

await sdk.tracking.syncFavorites(const ['sku-1', 'sku-2']);

await sdk.tracking.removeFromFavorites('sku-1');
```

`syncCart` and `syncFavorites` reject an empty list with an `ArgumentError` —
drop the last item through `removeFromCart` / `removeFromFavorites` instead.

### Stories

Only needed when you render stories yourself — the built-in stories view tracks
its own views and taps.

```dart
await sdk.tracking.storyView(
storyId: '4321',
slideId: '2',
code: 'main_stories',
);

await sdk.tracking.storyClick(
storyId: '4321',
slideId: '2',
code: 'main_stories',
);
```

`code` is the stories block; omit it and the native SDK uses the block it loaded
last. A tracked story also becomes the source of the events that follow it — the
same rule as [`setSource`](#attribution).

### Purchase

```dart
await sdk.tracking.purchase(
orderId: 'order-1024',
orderPrice: 149.8,
items: const [
PurchaseLineItem(id: 'sku-1', amount: 2, price: 49.9, fashionSize: '42'),
PurchaseLineItem(id: 'sku-2', amount: 1, price: 50.0),
],
);
```

Those three are required; everything else is optional:

```dart
await sdk.tracking.purchase(
orderId: 'order-1024',
orderPrice: 149.8,
items: const [PurchaseLineItem(id: 'sku-1', amount: 1, price: 149.8)],
deliveryType: 'courier',
deliveryAddress: 'Tverskaya 1, Moscow',
paymentType: 'card',
isTaxFree: false,
promocode: 'WINTER20',
orderCash: 100.0,
orderBonuses: 49.8,
orderDelivery: 5.0,
orderDiscount: 20.0,
channel: 'mobile_app',
custom: const {'store_id': 'msk-01'},
recommendedSource: const {'from': 'dynamic', 'code': 'main_page_block'},
stream: 'flutter',
segment: 'a',
);
```

`custom` goes on the wire under `custom`; keys that collide with the order's own
fields (`order_id`, `items`, `event`, `shop_id`, …) are rejected natively.

### Custom event

```dart
await sdk.tracking.custom(
'subscribed_to_newsletter',
category: 'account',
label: 'footer_form',
value: 1,
time: DateTime.now().millisecondsSinceEpoch ~/ 1000, // UNIX seconds
customFields: const {'plan': 'weekly'},
);
```

`customFields` is the free-form part: its entries are sent at the top level and
duplicated under `payload`. The SDK's own keys are reserved and rejected —
`event`, `time`, `category`, `label`, `value`, `source`, `payload`, `from`,
`code`, `stream`, `shop_id`, `did`, `sid`, `seance`, `segment`.

### Attribution

Events can carry the tool the user came from. Per call, for one event:

```dart
await sdk.tracking.productView(
'sku-1',
source: const TrackingSource(
type: TrackingSourceType.dynamicBlock,
code: 'main_page_block',
),
);
```

`source` is accepted by `productView`, `addToCart` and `addToFavorites` — the
events a recommendation leads to.

Or stored once, for the events that follow — the case where the source outlives
a single call, such as a user entering the catalog from a recommender block:

```dart
await sdk.tracking.setSource(
const TrackingSource(
type: TrackingSourceType.dynamicBlock,
code: 'main_page_block',
),
);

// Carries source=main_page_block without being told to.
await sdk.tracking.productView('sku-1');
```

The stored source lives natively per shop, survives restarts, and is kept for 48
hours or until it is replaced. A per-call `source` wins over the stored one, and
an order is attributed by the `recommendedSource` of the `purchase` call itself.

| `TrackingSourceType` | Wire value | Set by |
|---|---|---|
| `dynamicBlock` | `dynamic` | Dynamic recommender block |
| `chain` | `chain` | Recommendation chain |
| `bulk` | `bulk` | Bulk mailing |
| `transactional` | `transactional` | Transactional mailing |
| `instantSearch` | `instant_search` | Search suggestions |
| `fullSearch` | `full_search` | Full search results page |
| `stories` | `stories` | Stories block |
| `webPushDigest` | `web_push_digest` | Web push digest |

## License

MIT — see [LICENSE](LICENSE).
11 changes: 3 additions & 8 deletions android/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -86,14 +86,9 @@ android {
}

dependencies {
// REES46 Android SDK (JitPack).
// Published from github.com/rees46/android-sdk as `com.github.rees46:android-sdk:<tag>`.
// v2.36.0 is the first tag that ships the multi-instance `Rees46` facade.
val rees46AndroidSdkVersion = "v2.36.0"
add(
"rees46Implementation",
"com.github.rees46:android-sdk:$rees46AndroidSdkVersion",
)
// REES46 Android SDK.
val rees46AndroidSdkVersion = "v2.37.0"
add("rees46Implementation", "com.github.rees46:android-sdk:$rees46AndroidSdkVersion")

// Used directly by the push presenter (NotificationCompat / ContextCompat). The native SDK
// depends on the same version but as `implementation`, so it is not exposed transitively.
Expand Down
Loading
Loading