tagSOLUTE API Tutorial

Erste Schritte

Um Ihnen die ersten Schritte zu erleichtern, stellen wir Codebeispiele in den gängigsten Programmiersprachen zur Verfügung, die Sie innerhalb weniger Minuten zu den ersten Ergebnissen führen werden.

Unsere Beispiele besitzen alle eine gemeinsame Struktur.

  • eine Konfigurationsdatei

    beinhaltet die Definition der API URL und des Entwicklerschlüssels (DevKey)

  • eine API Datei

    beinhaltet Hilfsmethoden, um die API anzusprechen

  • eine Beispieldatei

    beinhaltet Programmcode, der illustriert, wie die Hilfsmethoden verwendet werden

  • ein JSON Bibliotheksverzeichnis

    beinhaltet die Dateien der JSON Bibliothek

Um die Beispiele auszuprobieren, müssen Sie lediglich:

  • Die Archivdatei, die in der Sektion Ihrer gewünschten Programmiersprache verlinkt ist, herunterladen und extrahieren
  • Sich auf unserer Homepage registrieren, um Ihren persönlichen Entwicklerschlüssel zu bekommen
  • Die Konfigurationsdatei entsprechend anpassen
  • Die Beispieldatei ausführen

Sobald Sie sich davon überzeugt haben, dass die Beispieldatei ohne Probleme auf Ihrem System läuft, können Sie sich eingehender mit unserer API Dokumentation beschäftigen und Ihre eigenen kreativen Anwendungsszenarien mit Hilfe der neuesten Mobile Tagging Technologie umsetzen.

Beschränkungen

Bitte beachten Sie, dass unsere regulären Entwicklerschlüssel auf 300 Tag-Erstellungen begrenzt sind (ohne Cache-Zugriffe). Sollten Sie Ihr Limit überschreiten und zusätzliche Tags benötigen, zögern Sie bitte nicht, uns zu kontaktieren, damit wir Ihnen ein entsprechendes Angebot unterbreiten können.

Unterstützte Programmiersprachen

Wir stellen derzeit Beispielcode für folgende Programmiersprachen bereit:

PHP

Archiv

Die Archivdatei für den PHP Beispielcode kann nachfolgend heruntergeladen werden:

  • php.zip (MD5: acd41859b3f5f9e0b47bebb281601fd6)

Anweisungen

  • Extrahieren Sie das Archiv in einen Ordner Ihrer Wahl.

  • Passen Sie die Datei config.php entsprechend Ihres Entwicklerschlüssels an.

    <?php

	define("TAGSOLUTE_DEV_KEY", "<enter your DevKey here>");
	define("TAGSOLUTE_API_URL", "http://www.tagsolute.de/cgi-bin/api.cgi");

?>

  • Falls Sie nicht mit PHP 5.2 arbeiten, kommentieren Sie bitte nachfolgende Zeile in der Datei example.php aus, um die zusätzliche JSON Bibliothek einzubinden.

    //require_once("json/JSON.php");

  • Führen Sie die Datei example.php von der Kommandozeile aus, z.B.:

    php example.php

  • Wenn der API Aufruf aus dem Beispiel erfolgreich ist, sollte die Ausgabe etwa so aussehen:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • Sollte der Aufruf fehlschlagen, sehen Sie eine Fehlermeldung, z.B.:

    Dev-Key '<enter your DevKey here>' could not be found.

    HINWEIS: Bitte stellen Sie sicher, dass Sie PHPs Standardwert "&" für den arg_separator.output php.ini Parameter verwenden - die Nutzung von "&amp;" (die bei einigen Versionen von XAMPP unter Windows verwendet wird) kann zu einem ApiCallArgumentListError Fehler führen, da unsere Skripte einen zusätzlichen, nicht unterstützten "amp" Parameter feststellen.

Beispielcode

Der für den API Aufruf nötige Programmcode befindet sich in der Datei example.php

<?php

	require_once("api.php");
	
	// uncomment the following line and point the require_once to your JSON library, if you use PHP<5.2
	//require_once("json/JSON.php");
	
	$mParams = array("sText" => "Hello, world!");
	
	// call the method
	$mResult = mxApiCall("GetTextTag", $mParams);
	
	if($mResult["bSuccessful"]) {
		print $mResult["jResult"];
	}
	else {
		print $mResult["jResult"]["sInfo"];
	}

	print "\n";
?>

JavaScript

Archiv

Die Archivdatei für den JavaScript Beispielcode kann nachfolgend heruntergeladen werden:

  • js.zip (MD5: dd7b69b6fd02c025990892cb61fbba42)

Anweisungen

  • Extrahieren Sie das Archiv in einen Ordner Ihrer Wahl.

  • Passen Sie die Datei config.js entsprechend Ihres Entwicklerschlüssels an.

    var TAGSOLUTE_DEV_KEY = "<enter your DevKey here>";
var TAGSOLUTE_API_URL = "http://www.tagsolute.de/cgi-bin/api.cgi";

  • Öffnen Sie die Datei example.html in Ihrem Internetbrowser.

  • Wenn der API Aufruf aus dem Beispiel erfolgreich ist, sollte der Inhalt des Eingabefeldes etwa so aussehen:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • Sollte der Aufruf fehlschlagen, sehen Sie eine Fehlermeldung im Eingabefeld, z.B.:

    Dev-Key '<enter your DevKey here>' could not be found.

Beispielcode

Der für den API Aufruf nötige Programmcode befindet sich in der Datei example.html

<html>
	<head>
		<title>tagSOLUTE JavaScript/AJAX API Call Sample</title>

		<script type="text/javascript" src="config.js"></script>
		<script type="text/javascript" src="http://theurer.cc/code/jsonSamples/jsr_class.js"></script>
		<script type="text/javascript" src="api.js"></script>
		
		<script language="javascript">

			function vxHelloWorld() {
			
				/* Call our the GetTextTag API method to generate a tag containing the text "Hello, world!".
				 *
				 * Arguments:
				 * 	None
				 *
				 * Returns:
				 *     Nothing
				 */
			
				mParams = new Object();
				mParams.sMethod = "GetTextTag";
				mParams.sText = "Hello, world!";
			
				vxApiCall(TAGSOLUTE_DEV_KEY, TAGSOLUTE_API_URL, mParams, vxShowResponse);
			
			}
			
			function vxShowResponse(pResponse) {
			
				/* Show the content of the request.
				 *
				 * Arguments:
				 *     pResponse -- the API response
				 *
				 * Returns:
				 *     Nothing
				 */
			
			
				if (pResponse["bSuccessful"]==true) {
					document.getElementById("wdgDebug").value = pResponse["jResult"];
				}
				else {
					alert(pResponse["jResult"]["sInfo"]);
				}
			}

		</script>

	</head>
	<body onload="vxHelloWorld()">

		URL of "Hello, world!" tag image:<br/>
		<input type="text" id="wdgDebug" style="width:600px;"/>

	</body>
</html>

HTML

Archiv

Die Archivdatei für den HTML Beispielcode kann nachfolgend heruntergeladen werden:

  • html.zip (MD5: d6a2e9e83a41b77ffec9a79e1bb47aaa)

Anweisungen

  • Extrahieren Sie das Archiv in einen Ordner Ihrer Wahl.

  • Passen Sie die Datei example.html entsprechend Ihres Entwicklerschlüssels an.

    <html>
	<body>
		<img src="http://www.tagsolute.de/cgi-bin/api.cgi?sDevKey=<enter your DevKey here>&sMethod=GetTextTag&sText=Hello,world!"/>
	</body>
</html>

  • Öffnen Sie die Datei example.html in Ihrem Internetbrowser.

  • Wenn der API Aufruf aus dem Beispiel erfolgreich ist, sehen Sie das entsprechende Tag in Ihrem Browserfenster

  • Sollte der Aufruf fehlschlagen, sehen Sie ein statisches Tag mit der Zeichenfolge "ERROR" in der Mitte.

Java

Archiv

Die Archivdatei für den Java Beispielcode kann nachfolgend heruntergeladen werden:

  • java.zip (MD5: 779e18b17f57d18901785274d4f5a012)

Anweisungen

  • Extrahieren Sie das Archiv in einen Ordner Ihrer Wahl.

  • Passen Sie die Datei Config.java entsprechend Ihres Entwicklerschlüssels an.

    public final class Config {

	public static String TAGSOLUTE_DEV_KEY = "<enter your DevKey here>";
	public static String TAGSOLUTE_API_URL = "http://www.tagsolute.de/cgi-bin/api.cgi";

}

  • Kompilieren Sie die Datei Example.java, z.B.

    javac -cp .;json Example.java

    HINWEIS: Sollten Sie mit einer JDK Version größer als 1.4 kompilieren, werden Sie eine Warnung erhalten, die sie auf die Verwendung von ungeprüften Hashmaps in unserem Beispielcode hinweist. Dies liegt daran, dass wir die Argumente an die API Aufrufe nicht strikt typisieren, da diese bei der Übermittlung via HTTP ohnehin verlorgen gehen würde. Sie können diese Warnung ohne weiteres einfach ignorieren.

    Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

  • Führen Sie die Datei Example.class von der Kommandozeile aus, z.B.:

    java -cp .;json Example

  • Wenn der API Aufruf aus dem Beispiel erfolgreich ist, sollte die Ausgabe etwa so aussehen:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • Sollte der Aufruf fehlschlagen, sehen Sie eine Fehlermeldung, z.B.:

    Dev-Key '<enter your DevKey here>' could not be found.

Beispielcode

Der für den API Aufruf nötige Programmcode befindet sich in der Datei Example.java

import java.util.HashMap;

import org.json.JSONException;
import org.json.JSONObject;

public class Example {

	public static void main(String[] aArgs) {
		
		HashMap mParams = new HashMap();
		mParams.put("sText", "Hello, world!");
		
		try {
			Api pApi = new Api();

			JSONObject pResponse = pApi.pxApiCall("GetTextTag", mParams);

			if (pResponse.getBoolean("bSuccessful")) {

				String sTagImageUrl = pResponse.getString("jResult");
				System.out.println(sTagImageUrl);

			}
			else {

				String sInfo = pResponse.getJSONObject("jResult").getString("sInfo");
				System.out.println(sInfo);

			}
		
		}
		catch(JSONException pException) {
			System.out.println("Error: " + pException.getLocalizedMessage());
		}
		
	}
	
}

Python

Archiv

Die Archivdatei für den Python Beispielcode kann nachfolgend heruntergeladen werden:

  • python.zip (MD5: f391e6a1b9127a5c733e29b64d463416)

Anweisungen

  • Extrahieren Sie das Archiv in einen Ordner Ihrer Wahl.

  • Passen Sie die Datei config.py entsprechend Ihres Entwicklerschlüssels an.

    TAGSOLUTE_DEV_KEY = "<enter your DevKey here>";
TAGSOLUTE_API_URL = "http://www.tagsolute.de/cgi-bin/api.cgi";

  • Führen Sie die Datei example.py von der Kommandozeile aus, z.B.:

    python example.py

  • Wenn der API Aufruf aus dem Beispiel erfolgreich ist, sollte die Ausgabe etwa so aussehen:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • Sollte der Aufruf fehlschlagen, sehen Sie eine Fehlermeldung, z.B.:

    Dev-Key '<enter your DevKey here>' could not be found.

Beispielcode

Der für den API Aufruf nötige Programmcode befindet sich in der Datei example.py

import api
        
mParams = {"sText": "Hello, world!"}

pResponse = api.mxApiCall("GetTextTag", mParams)

if pResponse["bSuccessful"]:
    print pResponse["jResult"]
else:
    print pResponse["jResult"]["sInfo"]

C#

Archiv

Die Archivdatei für den Python Beispielcode kann nachfolgend heruntergeladen werden:

  • cs.zip (MD5: 6a9b8236515c3f53ce4652e0383a3123)

Anweisungen

  • Extrahieren Sie das Archiv in einen Ordner Ihrer Wahl.

  • Passen Sie die Datei Config.cs entsprechend Ihres Entwicklerschlüssels an.

    namespace tagSOLUTE {
	
	class Config 
	{
		public static string TAGSOLUTE_DEV_KEY = "<enter your DevKey here>";
		public static string TAGSOLUTE_API_URL = "http://www.tagsolute.de/cgi-bin/api.cgi";
	}
}

  • Kompilieren Sie die Datei Example.cs, z.B.

    csc /r:json\Bin\Newtonsoft.Json.dll Api.cs Config.cs Example.cs

  • Führen Sie die Datei Example.exe von der Kommandozeile aus, z.B.:

    Example.exe

    HINWEIS: Stellen Sie sicher, dass sich die Datei Newtonsoft.Json.dll (from json/Bin) in Ihrer PATH Umgebung befindet, wenn Sie die EXE Datei ausführen, andernfalls erhalten Sie eine Fehlermeldung ähnlich zu der der Folgenden:

    Unhandled Exception: System.IO.FileNotFoundException: Could not load file or assembly 'Newtonsoft.Json, Version=1.3.0.0, Culture=neutral, PublicKeyToken=null' or one of its dependencies. Das System kann die angegebene Datei nicht finden.
File name: 'Newtonsoft.Json, Version=1.3.0.0, Culture=neutral, PublicKeyToken=null'
   at Example.Main(String[] aArgs)

WRN: Assembly binding logging is turned OFF.
To enable assembly bind failure logging, set the registry value [HKLM\Software\Microsoft\Fusion!EnableLog] (DWORD) to 1.
Note: There is some performance penalty associated with assembly bind failure logging.
To turn this feature off, remove the registry value [HKLM\Software\Microsoft\Fusion!EnableLog].

  • HINWEIS: Sollten Sie die untenstehende Fehlermeldung erhalten, versuchen Sie eventuell die EXE Datei von einem Netzwerklaufwerk aus zu starten. Überprüfen Sie in diesem Fall, ob das Ausführen von einem lokalen Laufwerk aus den Fehler behebt.

    Error: System.Security.SecurityException: Request for the permission of type 'System.Net.WebPermission, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089' failed.
   at System.Security.CodeAccessSecurityEngine.Check(Object demand, StackCrawlMark& stackMark, Boolean isPermSet)
   at System.Security.CodeAccessPermission.Demand()
   at System.Net.HttpWebRequest..ctor(Uri uri, ServicePoint servicePoint)
   at System.Net.HttpRequestCreator.Create(Uri Uri)
   at System.Net.WebRequest.Create(Uri requestUri, Boolean useUriBase)
   at System.Net.WebRequest.Create(String requestUriString)
   at tagSOLUTE.Api.sxGetUrlContent(String sUrl, Hashtable mParams)
The action that failed was:
Demand
The type of the first permission that failed was:
System.Net.WebPermission
The Zone of the assembly that failed was:
Internet

  • Wenn der API Aufruf aus dem Beispiel erfolgreich ist, sollte die Ausgabe etwa so aussehen:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • Sollte der Aufruf fehlschlagen, sehen Sie eine Fehlermeldung, z.B.:

    Dev-Key '<enter your DevKey here>' could not be found.

Beispielcode

Der für den API Aufruf nötige Programmcode befindet sich in der Datei Example.cs

using System;
using System.Collections;
using tagSOLUTE;
using Newtonsoft.Json;

class Example {

	public static void Main(string[] aArgs) {

		Hashtable mParams = new Hashtable();
		mParams.Add("sText", "Hello, world!");

		Api pApi = new Api();
		
		JavaScriptObject pResponse = pApi.pxApiCall("GetTextTag", mParams);

		if((bool) pResponse["bSuccessful"]) {
			Console.WriteLine(pResponse["jResult"]);
		}
		else {
			JavaScriptObject pJResult = (JavaScriptObject) pResponse["jResult"];
			Console.WriteLine(pJResult["sInfo"]);
		}
		
    }
    
}