Smart notifications

Source and statusCopy Anchor Link

The client's principleCopy Anchor Link

The document opens with four goals: keep the app present in the reseller's mind (« يخلي التطبيق ديما حاضر في بالو »), increase the number of orders, make sure no offer is missed, and help the reseller run their shop better. It states the rule « كل Notification لازم يكون عندها هدف تجاري »: every notification must have a commercial goal. It ends with a second rule the client is "100 % convinced" of: « كل Notification لازم يكون فيها زر Action », every notification carries an action button.

The specification turns this into three rules:

1. Every reseller notification has a group (NotificationGroup, the section of the Notification Centre) and an action (action { label, deepLink }). The transactional notifications already in the matrix get one too (NOT-10).
2. Smart notifications are rule-based and computed by the server from data the platform already holds: catalog, availability, prices, carts, orders, favorites, promotions. They are never sent by hand, except the commercial push, where HOCO picks the product and the audience.
3. Smart notifications are commercial (PROMOTIONAL category). They obey the anti-fatigue rules so that the Notification Centre stays useful and the reseller does not mute the app. Two decisions of 17 October still apply: resellers never see a stock quantity (STK-07), and guests receive no notification.

Release placementCopy Anchor Link

The ACADEMY group exists in the enum from V1, so the Notification Centre keeps its six sections. Until the module exists the section is hidden (NOT-09).

CatalogueCopy Anchor Link

Conventions used in the table:

• Channels: IN_APP is the inbox row, shown in the Notification Centre. PUSH goes to the reseller app; the reseller web has no web push in V1 and relies on the inbox and the live stream. No smart notification uses SMS: none meets the critical SMS rule, and marketing by SMS needs a prior opt-in (Law 18-07). The WhatsApp Business templates of V2 (NOT-08) are the channel to consider for SN-18 and SN-20 later.
• Category is the preference category (NotificationCategory). Group is the section of the Notification Centre (NotificationGroup).
• Recipients are always active, validated resellers whose account can order (store.canOrder) and who can see the product under its visibility rules (CAT-05). Guests, pending and suspended accounts receive nothing.
• Deep links are proposals, like the rest of the route table. The reseller app and the reseller web use the same paths.
• Settings in code are proposals for the settings catalogue. The defaults come from D-39 to D-44.

V1 typesCopy Anchor Link

The client gives each group a colour (red, orange, green, blue, purple, a star for suggestions). In the apps the colours become the tones of NotificationGroup, and Akram chooses the icons in DES-23.

V2 types (loyalty engine)Copy Anchor Link

Later / to decideCopy Anchor Link

Actions of the existing notificationsCopy Anchor Link

The client's examples set the tone: new product → « Commander maintenant », points earned → « Voir mon solde », new level → « Découvrir mes avantages », new video → « Regarder maintenant », one million left before Silver → « Commencer une commande ». The V1 events of the matrix get these default labels. Each template can override its label in BO-58.

Notification Centre and groupsCopy Anchor Link

Value	UI label (fr)	Meaning
URGENT	Urgent	Transactional and security notifications, urgent announcements.
PROMOTIONS	Promotions	Promotions, flash sales, price drops, commercial pushes, daily offers.
NEW_PRODUCTS	Nouveautés	New arrivals, back in stock, limited quantity, trending product, new catalogue.
LOYALTY	Points et niveaux	V2: points, levels, missions, gifts, challenges, Top 3.
ACADEMY	Academy	Later: HOCO Academy videos and quizzes; hidden while empty.
SUGGESTIONS	Suggestions	Reorder reminders, complementary products, abandoned cart.

Rules:

1. Home section (RA-09, RW-02): a card « Centre de notifications » under the attention slot. It shows one chip per visible group with its unread count, ordered Urgent, Promotions, Nouveautés, Suggestions (V2 adds Points et niveaux; Academy comes later), and the 3 latest unread items with their action buttons. With nothing unread it shows « Vous êtes à jour » and the 3 latest items. A chip opens the inbox filtered on that group.
2. Inbox (RA-26, RW-11): the filter chips become the group tabs: « Toutes », then the groups. The « Non lues » toggle stays.
3. Pop-ups: smart notifications never open a modal. In the foreground, a push appears as the usual in-app banner (realtime), and only for the URGENT group. Other groups only update the badge and the home section.
4. Groups apply to resellers only. Delegate and staff notifications have no group.
5. A notification's group is fixed by its template, never by the client app. A template that has no group defaults to URGENT for TRANSACTIONAL and SECURITY and to PROMOTIONS otherwise.

Anti-fatigue rulesCopy Anchor Link

Proposal to validate with HOCO (D-39, defaulted). Without limits, the 24 types could send a reseller several pushes a day. The client's own concern (« ما يحسش التطبيق يزعجو », the app must not feel like it harasses him) is the reason for these rules (NOT-17).

1. Caps on promotional pushes. At most 1 push per reseller per day and 3 per rolling 7 days for the PROMOTIONAL category. The settings are notifications.promotionalDailyCap (exists, 1) and notifications.promotionalWeeklyCap (new, 3). TRANSACTIONAL and SECURITY are never capped and do not count.
2. Capped means inbox only. A notification over the cap still writes its inbox row; it shows in the Notification Centre and in the badge. Only the push is dropped. Nothing is lost.
3. Priority for the day's push. When several promotional notifications compete for a reseller's slot within the same dispatch window, the push goes to the highest of: SN-18 flash sale → SN-02 back in stock → SN-20 abandoned cart → SN-23 commercial push → SN-21 price drop → SN-03 low stock → SN-04 promotion → SN-12 reorder → SN-14 complement → SN-01 new arrival → SN-17 trending → SN-19 catalogue. The others go to the inbox only. A commercial push counts like any other: the back-office cannot exceed the caps, but BO-57 shows the split before sending.
4. Quiet hours as already documented: PROMOTIONAL pushes only between 09:00 and 20:00, never on Friday before 14:00, and the Ramadan profile (quiet hours). A deferred push that would arrive after its TTL is dropped, for example a flash sale that has ended.
5. Merge of similar events. Events of the same type for the same reseller within 24 h become one notification with a count: « 3 nouveaux produits chez HOCO », « 2 produits de retour en stock ». The digest jobs batch arrivals and complements. The same product does not notify the same reseller twice in 7 days, whatever the type (back in stock, low stock, price drop, trending, complement).
6. Opt-out per group for the non-transactional groups (Promotions, Nouveautés, Suggestions; later Points et niveaux and Academy). The reseller sets it on RA-35 and RW-12, and it applies to push only, like every preference (NOT-06). The URGENT group is locked on. Turning off the category Offres et promotions turns off every promotional group at once.
7. Back-off (proposal): after 5 promotional pushes in a row that were not opened, the reseller's weekly cap drops to 1 for 30 days. The first opened push restores it.

Data and API impactCopy Anchor Link

Additive changes only: no V1 operation is renamed and no field is removed. They are made in SRV-39 (contract and schema) and used by SRV-40.

No operation id is added to endpoints.json: every change extends an existing operation.

French UI copyCopy Anchor Link

The apps are French-first. The table gives the French copy (fr, seed of NotificationTemplate) and keeps the client's own Arabic wording as the ar variant. The client's samples start with an emoji (a parcel, a flame, an hourglass, a party popper…); whether pushes keep a leading emoji is decided in DQA-10. The copy below leaves them out. The copy rules apply: title ≤ 40 characters, body ≤ 120, vous, no stock quantity.

Typical values for the length check: productName BOROFONE BX51 câble USB-C 1 m · promotionLabel Power Bank HOCO J101 · remaining 18 h · categoryName câbles · itemCount 4 · remainingAmount 1 000 000,00 DA. SN-04's client example (Power Bank at 2 100 DA instead of 2 500 DA) shows the promotional price next to the normal one on RA-25, not in the push. The push never carries a price, because prices depend on the customer type.

PlanCopy Anchor Link

The V1 work is six tasks: DES-23 (Akram: Notification Centre, action buttons, promotion tabs, flash-sale countdown), SRV-39 (contract and schema), SRV-40 (triggers and jobs), DSH-14 (back-office: commercial push, new catalogue, flash-sale fields, complementary products, settings), WEB-06 (reseller web) and MRA-11 (reseller app). Their dates are on the timeline. The extra 4 days on Anis's lane move Production go-live and Pilot starts by about four working days. Both still meet their targets in the milestones table. The pilot go / no-go moves by the same amount. If that matters more than scope, NOT-15 and then NOT-11 move after go-live first (D-38).

Ambiguities in the client textCopy Anchor Link