You need to host a simple text file on your site that describes to TntMPD what your various endpoints are. It's in the "ini" format. As an example, here's some actual endpoints:
The ini file has several sections ( //comments in blue should not be in actual file):
|
[APPLICATION]
MinimumVersion=3.0.17 // minimum version of TntMPD required
RecommendedVersion=3.0.17 // recommended version of TntMPD
[LetterService]
// if you move your query.ini url, you can put in a redirect here to update TntMPD
RedirectQueryIni=
// url to your logo (300x100)
LogoUrl=http://www.example.com/static/images/logo100.png
// url for new customer to learn about your service
AboutUrl=http://www.example.com/tntmpd
// for simple integration, just provide a url to TntMPD-specific instructions … done! … stop here
HowToOrderUrl=http://www.example.org/TNTMPDInstructions.pdf
// advanced: optional way to allow for authentication persistence via OAUTH access token
AccessTokenRequestUrl=https://www.example.com/tntmpd/authorize?tntdb=$TNTMPD_DATABASE$
AccessTokenCompleteUrl=https://www.example.com/tntmpd/authorize_callback
// advanced: optional endpoint for TntMPD to revoke access tokens
AccessTokenRevokeUrl=https://www.example.com/tntmpd/authorize_revoke?token=$ACCESS_TOKEN$
// advanced integration: provide url to upload CSV of partners
// return url to launch in user's default browser to complete order
CsvFieldNamesAreLocalized=FALSE
CsvUploadUrl=https://www.example.com/tntmpd/upload_file?v=1&ACCESS_TOKEN$
|
For simple integration...
You can stop with "HowToOrderUrl". The integration will look like this:
For advanced integration...
you must provide the "CsvUploadUrl". The integration will look like this:
Authentication is optional, but if you want to provide TntMPD with an OAUTH token, you can. The benefit is that the user doesn't have to login to your service each month to send their newsletter. To provide for OAUTH authentication, you must provide the following endpoints:
- AccessTokenRequestUrl
- AccessTokenCompleteUrl
If you include $TNTMPD_DATABASE$ in your AccessTokenRequestUrl, it will be substituted for the name of the current TntMPD database file. This way you can associate tokens with TntMPD databases for future reference. Once user is logged in, redirect the user to the AccessTokenCompleteUrl with the access token in the fragment portion of the url as #access_token=xxxxx In the CsvUploadUrl, $ACCESS_TOKEN$ is substituted for the OAUTH access token.
If you don't want to support an OAUTH access token, don't include any of the AccessToken* urls, and don't include $ACCESS_TOKEN$ in our CsvUploadUrl.
CsvUploadUrl
TntMPD will POST the current group as UTF-8 CSV text in the body of request.
If there is an error, the service should return:
- HTTP 401 if access token is invalid and needs to be reaquired.
- or HTTP status 200, with “ERROR” on first line of body, actual error message on 2nd line.
ERROR
Example error message |
If successful, return either:
- HTTP 200, with body of “LaunchBrowserUrl=xxxxxx”
- or a standard HTTP redirect (HTTP 301/302/303 w/ Location header)
The user's default browser will then be launched with the url returned so they can complete the order.
HOW TO TEST
To test your ini url, hold down the Ctrl (or Command key on a Mac) key and right-click on the drop down list:
READY?
When you have your url ready, send me an email at: troy.wolbrink@ccci.org. Tell me the NAME and URL in the email. Once I add you to the official list, TntMPD will be updated immediately.