Skip to content

Initial .NET SDK #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
illiminable merged 4 commits into from
Dec 17, 2012
Merged

Initial .NET SDK #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
398f36b
Initial commit of .net sdk for telesign.
Dec 17, 2012
ea42674
Remove old readme
Dec 17, 2012
f6ff246
Add documentation project.
Dec 17, 2012
084de1c
Fix url in readme
Dec 17, 2012
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 .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Build and Release folders.
bin/
obj/
docs/SandcastleHtml/

# Project property files.
.suo
.csproj.user

# Solution source files.
StyleCop.cache
19 changes: 19 additions & 0 deletions LICENSE.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
Copyright (c) 2012 TeleSign Corp.

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
4 changes: 0 additions & 4 deletions README.md
View file
Open in desktop

This file was deleted.

180 changes: 180 additions & 0 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
========
TeleSign
========

:Info:
For more information, visit the `TeleSign web site <http://www.TeleSign.com>`_.
For the latest source code, visit the `TeleSign github repository <http://github.com/TeleSign/csharp_telesign/tree>`_.

:Author:
Telesign Corp.

---------------------------------
TeleSign Web Services: .NET SDK
---------------------------------

**TeleSign Web Services** conform to the `REST Web Service Design Model <http://en.wikipedia.org/wiki/Representational_state_transfer>`_. Services are exposed as URI-addressable resources through the set of *RESTful* procedures in our **TeleSign REST API**.

The **TeleSign .NET SDK** is a Microsoft .NET component that provides an interface to `TeleSign Web Services <http://www.telesign.com/products-demos/>`_.

It contains a .NET Framework class library that presents our web services in an intuitive, hierarchical object model, so you can create and manipulate them in the way you're accustomed to. You can use this SDK to build TeleSign‑based .NET applications.

Authentication
--------------

**You will need a Customer ID and API Key in order to use TeleSign’s REST API**. If you are already a customer and need an API Key, you can generate one in the `Client Portal <https://portal.telesign.com>`_. If you are not a customer and would like to get an API Key, please contact `support@telesign.com <mailto:support@telesign.com>`_

You supply your credentials to the API either by editing the TeleSign.config.xml file and filling in the CustomerId and
SecretKey values or you can create the credentials in code. Passing null to the service constructors uses the file.

**Option 1. Supply TeleSign.config.xml**

>>>
<?xml version="1.0" encoding="utf-8" ?>
<TeleSignConfig>
<ServiceUri>https://rest.telesign.com</ServiceUri>
<Accounts>
<Account name="default">
<!-- Enter your customer id and secret key here. -->
<CustomerId>99999999-9999-9999-9999-000000000000</CustomerId>
<SecretKey>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==</SecretKey>
</Account>
</Accounts>
</TeleSignConfig>


**Option 2. Supply the credential with code**

>>>
Guid customerId = Guid.Parse("*** Customer ID goes here ***");
string secretKey = "*** Secret Key goes here ***";
TeleSignCredential credential = new TeleSignCredential(
customerId,
secretKey);
TeleSignServiceConfiguration config = new TeleSignServiceConfiguration(credential);
// For Verify Sms or Call Service
VerifyService verify = new VerifyService(config);
// For PhoneId products
PhoneIdServer phoneId = PhoneIdService(config);

Operating Modes
---------------

You can use the TeleSign .NET SDK in either of two modes. The rich mode is recommended and handles all aspects of authentication and response parsing, providing a high level object model.

+----------------------+--------------------------------------------------------------------------+
| Mode | Description |
+======================+==========================================================================+
| Rich | Provides an object-oriented framework that models web services as |
| | high-level actors, and low-level processes as mediator objects. |
| | Automatically parses the JSON data from server responses, and creates |
| | Response objects from it. |
| | |
+----------------------+--------------------------------------------------------------------------+
| Raw | Abstracts the interaction with only the web services. Method calls |
| | return the web service's JSON response bodies verbatim. This gives you |
| | the flexibility of handling the response processing any way you want. |
| | |
+----------------------+--------------------------------------------------------------------------+

Documentation
-------------

All classes and functions are documented with XML comments. Installing `Sandcastle Help File Builder
<http://shfb.codeplex.com/>`_ will allow you to build the HTML version of the documentation locally.

Rich Mode Classes
-----------------

+----------------------+--------------------------------------------------------------------------+
| Mode | Description |
+======================+==========================================================================+
| PhoneIdService.cs | The **PhoneIdService** class exposes four services that each provide |
| | information about a specified phone number. |
| | |
| | ``public PhoneIdStandardResponse StandardLookup(string phoneNumber)`` |
| | Retrieves the standard set of details about the specified phone |
| | number. This includes the type of phone (e.g., land line or mobile), |
| | and it's approximate geographic location. |
| | ``public PhoneIdScoreResponse ScoreLookup(string phoneNumber)`` |
| | Retrieves a score for the specified phone number. This ranks the |
| | phone number's "risk level" on a scale from 0 to 1000, so you can |
| | code your web application to handle particular use cases (e.g., to |
| | stop things like chargebacks, identity theft, fraud, and spam). |
| | ``public PhoneIdContactResponse ContactLookup(string phoneNumber)`` |
| | In addition to the information retrieved by *standard*, this service |
| | provides the Name & Address associated with the specified phone |
| | number. |
| | |
| | ``public PhoneIdLiveResponse LiveLookup(string phoneNumber)`` |
| | In addition to the information retrieved by *standard*, this service |
| | provides information about the subscriber status, device status, |
| | roaming status and roaming country. |
| | |
| | |
+----------------------+--------------------------------------------------------------------------+
| VerifyService.cs | The **VerifyService** class exposes two services for sending users a |
| | verification token (a three to five-digit number). You can use this |
| | mechanism to simply test whether you can reach users at the phone number |
| | they supplied, or you can have them use the token to authenticate |
| | themselves with your web application. In addition, this class also |
| | exposes a service that allows you to confirm the result of the |
| | authentication. |
| | |
| | You can use this verification factor in combination with *username* |
| | & *password* to provide *two-factor* authentication for higher |
| | security. |
| | |
| | ``public VerifyResponse SendSms(string phoneNumber)`` |
| | Send a text message containing the verification code to the |
| | specified phone number (supported for mobile phones only). |
| | |
| | ``public VerifyResponse InitiateCall(string phoneNumber)`` |
| | Calls the specified phone number, and using a recorded message speaks|
| | the verification code to the user. |
| | |
| | ``public VerifyResponse ValidateCode(`` |
| | ``string referenceId,`` |
| | ``string verifyCode)`` |
| | |
| | Checks the code supplied is correct. You make this call in your |
| | application after users complete the authentication transaction. |
| | |
| | ``public VerifyResponse CheckStatus(string referenceId)`` |
| | |
| | |
+----------------------+--------------------------------------------------------------------------+

Code Example: PhoneId Contact Lookup
------------------------------------
These example assume you are using the file for authentication/configuration described above.

>>>
string phoneNumber = "+1 555-555-5555";
PhoneIdService service = new PhoneIdService();
PhoneIdContactResponse response = service.ContactLookup(phoneNumber);
Console.WriteLine("Phone Number: {0}", phoneNumber);
Console.WriteLine("Name : {0}", response.Contact.FullName);
Console.WriteLine("Address :\r\n{0}", response.Contact.GetFullAddress());

Code Example: Initiate Sms Verify
---------------------------------
>>>
string code = "1234";
string phoneNumber = "+1 555-555-5555";
string language = "en";
VerifyService verify = new VerifyService();
VerifyResponse verifyResponse = verify.SendSms(phoneNumber, code, string.Empty, language);


For more examples, see the documentation or browse the example command line app source code in
**Commands.cs** in the **TeleSign.TeleSignCmd** project.


Support and Feedback
--------------------

For more information about the Phone Verify and PhoneID Standard services, please contact your TeleSign representative:

Email: `support@telesign.com <mailto:support@telesign.com>`_

42 changes: 42 additions & 0 deletions docs/Code_Examples.aml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="d8ee9679-8708-4b36-89c8-37baadf1f1ce" revisionNumber="1">
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:WDCML="http://microsoft.com/wdcml">

<summary>
<para>
To help get you started, we included a simple console application called <legacyBold>TeleSignCmd</legacyBold>,
that demonstrates the SDK's functionality. Use this application as a learning aid.
</para>
</summary>

<introduction>
<para>
Build the project, and then step through the code to see how it works.
</para>
<alert class="tip">
<para>
Feel free to use it for code snippets—to help you get off to a productive start.
</para>
</alert>
</introduction>

<section>
<title>The TeleSignCmd Project</title>
<content>
<para>
You can find the console in the <legacyBold>TeleSignCmd</legacyBold> project, beneath the <legacyBold>TeleSign.Sdk</legacyBold> solution.
</para>
<mediaLink>
<image xlink:href="TeleSignCmd" />
</mediaLink>
</content>
</section>

<relatedTopics>
<link xlink:href="4ea0bd57-de15-4ea2-ac1e-2561078f33d9"/>
</relatedTopics>
</developerConceptualDocument>
</topic>
104 changes: 104 additions & 0 deletions docs/Core_Classes.aml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="8f657d07-db62-4a3a-b4bd-2d52c25bebfc" revisionNumber="1">
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">

<introduction>
<para>The following classes encapsulate the core functionality of the SDK.</para>
</introduction>
<section>
<title></title>
<content>
<table>
<row>
<entry>
<para>
<legacyBold>Source File</legacyBold>
</para>
</entry>
<entry>
<para>
<legacyBold>Description</legacyBold>
</para>
</entry>
</row>
<row>
<entry>
<para>
<legacyBold>VerifyService.cs</legacyBold>
</para>
</entry>
<entry>
<para>Contains the high-level API for interacting with the Verify service. It abstracts the underlying details of interacting with the REST API. The basic usage is to initiate a call or SMS to a phone number, and then check the status of that transaction. </para>
</entry>
</row>
<row>
<entry>
<para>
<legacyBold>PhoneIdService.cs</legacyBold>
</para>
</entry>
<entry>
<para>Contains the high-level API for interacting with the Phone Id service. It abstracts the underlying details of interacting with the REST API, and allows you to simply specify the phone number you want details about.</para>
</entry>
</row>
<row>
<entry>
<para>
<legacyBold>TeleSignService.cs</legacyBold>
</para>
</entry>
<entry>
<para>
Contains the lowest-level of interaction with the REST API service. In this file you can see how the request and response objects are constructed, which headers are used in the requests, and how the authentication is performed (including the construction of the <legacyBold>StringToSign</legacyBold> object).
</para>
<para>
For more information, see the <externalLink>
<linkText>TeleSign REST API documentation</linkText>
<linkUri>https://portal.telesign.com/docs/index.html</linkUri>
</externalLink>.
</para>
</entry>
</row>
<row>
<entry>
<para>
<legacyBold>RawVerifyService.cs</legacyBold>
</para>
</entry>
<entry>
<para>Contains the lower-level interaction to the Verify service. Look here to see the parameters the service requires.</para>
</entry>
</row>
<row>
<entry>
<para>
<legacyBold>RawPhoneIdService.cs</legacyBold>
</para>
</entry>
<entry>
<para>Contains the lower-level interaction to the Phone Id service. Look here to see the parameters the service requires.</para>
</entry>
</row>
<row>
<entry>
<para>
<legacyBold>TeleSignResponse.cs</legacyBold>
</para>
</entry>
<entry>
<para>The base class for all responses. Contains the basic transaction status information. Look at the other *Response.cs files to see the data model returned from the API.</para>
</entry>
</row>
</table>
</content>
</section>
<relatedTopics>
<link xlink:href="9af6cf0a-fd66-4584-a80a-91cda099a967">Overview</link>
<link xlink:href="a9f7180c-377a-43e4-8300-81dcadf4f6e3">SDK Operating Modes</link>
<link xlink:href="c5db90e5-f4d4-4ef5-a301-f273c5912311">TeleSign Web Services</link>
<link xlink:href="d04c81bc-5c8d-4c00-bcf8-d91a4f66313d">TeleSign Namespaces &amp; Classes</link>
</relatedTopics>
</developerConceptualDocument>
</topic>
Loading