Welcome‎ > ‎Version 3‎ > ‎Publisher Api‎ > ‎

Building Your Own Site

**This page is a work in progress**

Affiliate Tracking

It is recommended to always scrape the querystring looking for affiliate markers. It is up to the website created to determine.  For any site built on the group commerce platform, we use "gc_affiliateid".  When it is present stick the "affiliateid", "affiliatesource" parameters into a cookie along with a timestamp.

Then pass this data along for the calls that expect this for affiliate tracking.

AffiliateInfo.AffiliateId int32 When recording affiliate tracking, the id of the affiliate.

AffiliateInfo.AffiliateSource string When recoding affiliate tracking, the source of the affiliate.

AffiliateInfo.CreateUnixTimestamp int64 When recording affiliate tracking, the Unix time or POSIX time the affiliate tracking started recording. 

The AffiliateInfo object is used for
  * Purchase
  * Add Email Lead
  * Update Subscription Extension

If you have affiliates, it is also recommended that you build a simple affiliate feed (RSS or other) that they can use to get the most recent offers.  For example, you might wish to support something like http://www.mydealssite.com/affiliate/offers?affiliateid=5.  To build this endpoint, we recommend using the Broadcast API's Get Broadcast Offers method.  You will have to adjust the offer urls on each returned offer to include an identifying query string.  So, if affiliate id 5 makes a request to /affiliate/offers?affiliateid=5, the urls of the returned offers should all have "affiliateid=5" in their query strings so that you can track affiliates as described above.



Segmenting Users

Segmenting a user can provide value in two ways.  The first is purchase tracking.  When a purchase is made, the SegmentKey can be passed along with the purchase method and used inside pub admin for reporting.  The second way is a better user experience.  It is possible to always geo code the user to determine which segment to show.  However, a better experience might be to cookie the user to the last segment they viewed.  There might be a reason the consumer changed segments and would be nice to remember their override.



Voucher Previews
Pub Admin users may want to preview the vouchers they create.  In order to do this, you need to support a url route for voucher preview.  (The URL routes will look like http://www.yourdomain.com/previewVoucher?SecretKey=<secretkey>&Code=Preview-Code.)



Emails/Email Callbacks
There are several events in the Group Commerce system which trigger emails, and they are broken up into two classes of emails: Orders and Profiles.

When configured in Pub Admin, our system will POST callbacks to URLs you specify with the information necessary to render and send email content.

Your endpoints should respond with the exact content "OK" (without quotes) on success; anything else for a failure (we use the string "FAIL").
In the event of a failure, our system will retry the request sometime later.

Requests:

Field Data Type Nulls Description
cultureCode string
Y
Culture Code
emailType string

The event for which this email should be sent.
See below for the types
dataJson
JSON

A JSON object which will provide all of the information that you could
not otherwise retrieve. e.g., an OrderId, but not a fully-baked Order object.
(Subsequent API requests will be needed to gather remaining data.)
See below for the JSON formats, based on the emailType
sharedKey string
  A secret key shared between our systems.
 

cultureCode:
This will determine the culture into which the email should be rendered.
emailType:
    • Profile Related
      • welcome - Sent on Profile creation
      • forgotpassword - Sent when a user initiates the reset password process
    • Order Related
      • canceled - Sent when an order is cancelled
      • chargedfailed - Sent when an attempt to process a charge fails (as opposed to failed authorization)
      • fulfilled - Sent when an order or partial order has been fulfilled.  In the event that an order is fulfilled in parts, this email will be sent more than once.  Included in the request is the list of order detail itemkeys which have been fulfilled.
      • placed - Sent when an order is placed
      • raoaward - Sent when a user has earned a free offer through referrals
      • raopurchase - Sent to a referring user that one of their referred users has purchased, making them one referral closer to a free item.
      • rafaward - Sent when a user has earned credit toward future purchases through referrals
      • voucherReminder - Sent when a voucher is due to expire
dataJson:
JSON data which will contain all of the necessary order or profile data needed to render this email.
See below for more details on the format of dataJson determined by the emailType above.
sharedKey:
Defined in Pub Admin, use this key to authenticate the request.
Use the API's GetPublisher call and compare the response object's emailNotificationCallbackSharedKey to this sharedKey.


Some things to consider:
  • The timeout on this call is 90 seconds.
  • In most cases, you will need to make further API requests to gather more detailed information used to render an email.  For example, Order email requests contain an orderId, so a call to the GetOrderById API endpoint will be required to gather details about that order.


Our implementation:
  1. We use the URLs /callback/order and /callback/profile in our implementations.
  2. We make the necessary API calls to gather data and render our email templates
  3. We use the API's sendEmail endpoint to actually send the content
  4. We then use the sendEmailResponse success property to determine what to send in the callback response.

More thorough implementations might include a message queue such that your site can accept the email callback requests, respond immediately, and render/send the email with a background process.  This would lighten the load on your web servers and virtually eliminate the callback timeout concerns.


dataJson Objects (with sample data):

Welcome (email)
{
   
"userKey": "key representing the user"
}

Reset Password (email)
{
    "userKey": "key representing the user",
    "resetToken": "reset token" // see: Reset Password
}

Order Cancelled (order)
{
    "orderId": 12345,
    "orderDetailItemKeys": ["
key", ...], // see: Order Detail itemKey
    "reason": 0 // 0: Customer Service (CS) Cancelled; 1: Credit Card Failed; 2: CS Refund; 3: CS Void; 4: Auto Refund Unfulfilled Order
}

Charge Failed (order)
{
    "orderId": 12345
}

Order Fulfilled (order)
{
    "orderId": 12345,
    "orderDetailItemKeys": ["key", ...], // see: Order Detail itemKey
    "giftNotification": false
}

Order Placed (order)
{
    "orderId": 12345
}

Refer an Offer Award (order)
{
    "orderId": 12345,
    "offerOptionId": 23456
}

Refer an Offer Purchase (order)
{
    "orderId": 12345,
    "offerOptionId": 23456,
    "howManyNeeded": 3,
    "howManyPurchased": 1
}

Refer a Friend Award (order)
{
    "userKeyToGetNotification": "user key",
    "orderIdThatTriggered": 12345
}

Voucher Reminder (order)
{
    "orderId": 12345,
    "itemKey": "key" // see: Order Detail itemKey
}


Subpages (1): Emails/Email Callbacks
Comments